helmfile/docs/shared-configuration-across-teams.md

Shared Configuration Across Teams

Assume you have two or more teams, each work for a different internal or external service, like:

• Product 1
• Product 2
• Observability

The simplest helmfile.yaml that declares the whole cluster that is composed of the three services would look like the below:

releases:
- name: product1-api
  chart: product1-charts/api
  # snip
- name: product1-web
  chart: product1-charts/web
  # snip
- name: product2-api
  chart: saas-charts/api
  # snip
- name: product2-web
  chart: product2-charts/web
  # snip
- name: observability-prometheus-operator
  chart: stable/prometheus-operator
  # snip
- name: observability-process-exporter
  chart: stable/prometheus-operator
  # snip

This works, but what if you wanted to a separate cluster per service to achieve a smaller blast radius?

Let's start by creating a helmfile.yaml for each service.

product1/helmfile.yaml:

releases:
- name: product1-api
  chart: product1-charts/api
  # snip
- name: product1-web
  chart: product1-charts/web
  # snip
- name: observability-prometheus-operator
  chart: stable/prometheus-operator
  # snip
- name: observability-process-exporter
  chart: stable/prometheus-operator
  # snip

product2/helmfile.yaml:

releases:
- name: product2-api
  chart: product2-charts/api
  # snip
- name: product2-web
  chart: product2-charts/web
  # snip
- name: observability-prometheus-operator
  chart: stable/prometheus-operator
  # snip
- name: observability-process-exporter
  chart: stable/prometheus-operator
  # snip

You will (of course!) notice this isn't DRY.

To remove the duplication of observability stack between the two helmfiles, create a "sub-helmfile" for the observability stack.

observability/helmfile.yaml:

- name: observability-prometheus-operator
  chart: stable/prometheus-operator
  # snip
- name: observability-process-exporter
  chart: stable/prometheus-operator
  # snip

As you might have imagined, the observability helmfile can be reused from the two product helmfiles by declaring helmfiles.

product1/helmfile.yaml:

helmfiles:
- ../observability/helmfile.yaml

releases:
- name: product1-api
  chart: product1-charts/api
  # snip
- name: product1-web
  chart: product1-charts/web
  # snip

product2/helmfile.yaml:

helmfiles:
- ../observability/helmfile.yaml

releases:
- name: product2-api
  chart: product2-charts/api
  # snip
- name: product2-web
  chart: product2-charts/web
  # snip

Using sub-helmfile as a template

You can go even further by generalizing the product related releases as a pair of api and web:

shared/helmfile.yaml:

releases:
- name: product{{ env "PRODUCT_ID" }}-api
  chart: product{{ env "PRODUCT_ID" }}-charts/api
  # snip
- name: product{{ env "PRODUCT_ID" }}-web
  chart: product{{ env "PRODUCT_ID" }}-charts/web
  # snip

Then you only need one single product helmfile

product/helmfile.yaml:

helmfiles:
- ../observability/helmfile.yaml
- ../shared/helmfile.yaml

Now that we use the environment variable PRODUCT_ID to as the parameters of release names, you need to set it before running helmfile, so that it produces the differently named releases per product:

$ PRODUCT_ID=1 helmfile -f product/helmfile.yaml apply
$ PRODUCT_ID=2 helmfile -f product/helmfile.yaml apply

Inheriting parent configuration with inherits:

By default a sub-helmfile is independent: it does not see the repositories:, helmDefaults:, environments:, etc. declared in the parent that includes it. To share configuration you either extract it into a separate file referenced via bases: from each sub-helmfile, or — more concisely — let each sub-helmfile opt into inheriting specific categories from its parent with inherits:.

# parent helmfile.yaml
repositories:
- name: release-charts
  url: registry.example.com/release/helm-charts
  oci: true

helmfiles:
- path: myapp.yaml
  inherits:
  - repositories
  - environments

myapp.yaml now sees the release-charts repository and the parent's resolved environment values, without having to re-declare them.

Allowed values

inherits: accepts a list. Each entry must be one of:

Key	What is inherited
repositories	Parent repository definitions (appended; child entry wins on name conflict).
helmDefaults	Parent helm defaults; parent fills the child's unset sub-fields, child's set sub-fields win (see caveat below).
commonLabels	Parent common labels; child's keys win on conflict.
apiVersions	Parent API versions (appended and de-duplicated).
kubeVersion	Parent kube version, only when the child left it empty.
templates	Parent templates; child's template wins on name conflict.
environments	The parent's resolved environment values (see note below).

Precedence

Child wins, parent fills gaps — consistent with bases:. Slices like repositories accumulate (parent first); maps (commonLabels, templates) are unioned with the child's keys winning; helmDefaults is deep-merged so the child overrides individual sub-fields it sets.

Caveat: helmDefaults and zero values

helmDefaults is deep-merged field-by-field, and Go value types cannot distinguish an explicitly-set zero value from "unset". So a child that sets a sub-field to its zero value (for example atomic: false to disable an inherited atomic: true) will still see the parent's non-zero value fill in. To override such a field, set it to a non-zero value, or omit helmDefaults from inherits: and declare the block in full on the child. The common case — a child that omits helmDefaults entirely and inherits the parent's — is unaffected.

Note on environments

environments inherits the parent's already-resolved values (including CLI overrides and decrypted secrets), not the environments: declaration block. This avoids ambiguity around the directory that relative values files resolve against (the parent resolves them once). The child's own environments: block, if any, still takes precedence per key.

Transitive inheritance

Inheritance is opt-in at every level but the values propagate. If a parent inherits repositories and the child in turn has its own helmfiles: entries declaring inherits: [repositories], the grandchild receives the accumulated set.

inherits: vs bases:

	bases:	inherits:
Model	Pull — each file lists files to merge into itself	Push — the parent pushes its config to the child
Where the shared config lives	Must live in a separate file	Can live inline in the parent
Repetition	bases: must be repeated in every sub-helmfile	Declared once, per sub-helmfile entry

They are complementary: use bases: for cross-team reusable building blocks (environment defaults, shared helm defaults), and inherits: to let a sub-helmfile consume the parent's inline configuration without duplication.

Footgun warning

If a sub-helmfile references a repository that the parent declares but the child does not (and repositories is not inherited), helmfile prints a warning suggesting inherits: [repositories] instead of failing later with a confusing repo not found (see #1495).