Introduction

Helm can override nested values from the command line, but arrays are where many charts become awkward to manage. The short answer is that Helm can target an array element by index, but it cannot natively search an array for the item whose name equals some value and then update one property inside that item.

What Helm Supports on the Command Line

Helm's --set, --set-string, and --set-json flags work with path expressions. For arrays, that means numeric indexes.

Suppose your values.yaml contains:

1workers:
2  - name: api
3    replicas: 2
4  - name: jobs
5    replicas: 1

You can update the first item's replicas like this:

helm upgrade demo ./chart \
  --set workers[0].replicas=5

That works because Helm knows exactly which position to modify. It does not inspect the name field and infer the index for you.

The Limitation with Arrays of Objects

What Helm does not support well is a selector-like expression such as "find the item where name is api and set replicas to 5." In other words, there is no native equivalent of:

workers[name=api].replicas=5

That kind of path syntax would be convenient, but Helm does not provide it.

This limitation matters because array indexes are fragile. If another item is inserted at the beginning of the list, workers[0] may no longer be the api worker.

The Best Fix: Use a Map Instead of an Array

If you control the chart design, the maintainable solution is to model named items as a map keyed by name.

Instead of this:

1workers:
2  - name: api
3    replicas: 2
4  - name: jobs
5    replicas: 1

Prefer this:

1workers:
2  api:
3    replicas: 2
4  jobs:
5    replicas: 1

Now the command-line override is stable and readable:

helm upgrade demo ./chart \
  --set workers.api.replicas=5

This is one of those cases where chart data modeling directly affects operability. If users need targeted overrides, arrays of named maps are usually the wrong structure.

If You Cannot Change the Chart

If the chart is fixed and uses an array, you have two realistic options.

First, use the numeric index when the ordering is stable and documented:

helm upgrade demo ./chart \
  --set workers[1].replicas=3

Second, preprocess the values file with a tool such as yq and then pass the modified file to Helm.

Example using yq:

yq '(.workers[] | select(.name == "api") | .replicas) = 5' values.yaml > values.patched.yaml
helm upgrade demo ./chart -f values.patched.yaml

That is often the least bad option when you need selection by content rather than by index.

Make Sure the Templates Match the Structure

If you redesign the values from an array to a map, the chart templates must change too. An array is usually rendered with a range loop over list items, while a map is rendered by iterating keys and values.

Example Helm template for the map version:

1{{- range $name, $config := .Values.workers }}
2apiVersion: apps/v1
3kind: Deployment
4metadata:
5  name: {{ $name }}
6spec:
7  replicas: {{ $config.replicas }}
8{{- end }}

That is the real cost of the redesign, but the resulting override behavior is much easier to operate in CI and release pipelines.

Choosing the Right Override Mechanism

Use --set when:

• the value is small
• the path is stable
• you are automating a simple environment-specific change

Use a values file when:

• several fields change together
• the structure is complex
• array order is fragile

Use preprocessing with yq when:

• you cannot change the chart design
• the chart uses arrays of named objects
• the override must target an item by content

Common Pitfalls

The most common mistake is assuming Helm can select array items by a property such as name. It cannot through native --set syntax.

Another mistake is relying on indexes that are not stable across chart versions. A minor upstream change can silently redirect the override to the wrong item.

Teams also use long --set chains for highly structured values. At that point, a dedicated values file is clearer and less error-prone.

Finally, chart authors often choose arrays where a map would better represent a keyed collection. If operators need precise overrides, chart shape matters as much as chart content.

Summary

• Helm can override a field inside an array item only by index, not by matching a property value.
• '--set workers[0].replicas=5 works when the array order is stable.'
• If you control the chart, prefer a map keyed by logical name for cleaner overrides.
• If you cannot change the chart, preprocess the values with yq and pass the patched file to Helm.
• Good chart data modeling makes command-line overrides predictable and maintainable.