Skip to content
Tutorials Center
My learning

Topics

Lesson 22 of 37 ยท Helm, Kustomize and Config Management

Multiple Sources and Value Files from Another Repo

Combine a public Helm chart with your own values from Git using spec.sources and ref, plus rules for revisions, paths, rollback and common mistakes.

A very common situation: the chart comes from the vendor's repository, but your values belong in your Git repository, reviewed by your team. A single source cannot express that, because the chart and the values live in different places. Multiple sources solves it.

The problem

Without multiple sources you had two poor options: copy the chart into your repo (and lose upstream updates) or paste values inline in the Application (hard to review, one file per app). With spec.sources an Application takes a list of sources that are rendered together.

Chart plus values

YAML
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: ingress-nginx
  namespace: argocd
spec:
  project: platform
  sources:
    - repoURL: https://kubernetes.github.io/ingress-nginx
      chart: ingress-nginx
      targetRevision: 4.11.3
      helm:
        valueFiles:
          - $values/clusters/prod/ingress-nginx/values.yaml
    - repoURL: https://git.example.com/platform/gitops.git
      targetRevision: main
      ref: values
  destination:
    name: in-cluster
    namespace: ingress

Two things make it work:

  • The second source has ref: values. It contributes no manifests by itself; it only names a checkout of that repository.
  • The first source reads files from that checkout with the $values/ prefix. The name after $ must match the ref.

Note that spec.source (singular) and spec.sources (plural) are alternatives. Use only one.

flowchart LR
  C["Chart repo: ingress-nginx 4.11.3"] --> R["Render"]
  G["Git repo, ref: values"] -- "$values/... files" --> R
  R --> M["Manifests"]

A ref source provides files, not manifests.

More than two sources

Any number of sources is allowed. A common pattern adds a second manifest source for extra resources (for example a NetworkPolicy) that the chart does not include:

YAML
sources:
  - repoURL: https://charts.example.org/stable
    chart: web
    targetRevision: 1.2.0
    helm:
      valueFiles:
        - $cfg/envs/prod/web.yaml
  - repoURL: https://git.example.com/platform/gitops.git
    targetRevision: main
    ref: cfg
  - repoURL: https://git.example.com/platform/gitops.git
    targetRevision: main
    path: envs/prod/extras

The third source has a path and no ref, so its manifests are added to the result. The same repository can appear several times.

Revisions and rollback

Every source has its own targetRevision. That has consequences:

  • Pinning: pin the chart to an exact version and track a branch for values, or pin both to tags for a frozen release.
  • Sync status reports one revision per source, and the UI shows them all.
  • History records all revisions, so a rollback restores the chart version and the values commit together.
  • CLI: commands that took a single revision now take one per source. For example argocd app set my-app --source-position 1 --revision 4.11.4 changes the first source (positions start at 1).

Webhooks and caching

A push to the values repository should refresh the Application. Argo CD matches webhook events against every source's repository, so the Application refreshes when either changes. If you use manifest-generate-paths, remember it applies per source with the . and ../ conventions described in the performance lesson (High Availability and Performance).

Limits to know

Behavior Detail
Mixed tools Each source is rendered by its own tool (Helm, Kustomize, directory)
ref sources Only usable by valueFiles of other sources via $name/path
Missing file The render fails unless ignoreMissingValueFiles: true
UI and CLI Some older tooling shows only the first source; use a current CLI
Support Check the release notes of your Argo CD version for feature status

Keep one rule of thumb: one Application, one deployable unit. Do not stack unrelated charts into one Application just because you can; failures and sync status would be shared.

Stand-in: resolving $ref paths

The runner has no Git, so this stand-in models just the path resolution: how $values/... is turned into a file from the right repository.

Python Stand-in: resolve value file references

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Common mistakes

  • Using $values without a source that declares ref: values.
  • Forgetting the leading slash difference: the path after $values/ is relative to the repository root, not to a path.
  • Setting both source and sources.
  • Tracking main for values while the chart is pinned, then being surprised that a values change deploys immediately. That is often what you want, but make it a decision.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does a source with ref: values contribute on its own?

    ref sources are only file providers, addressed with $name/path.
  2. 2. How do you refer to a values file in the ref named config?

    The prefix is a dollar sign followed by the ref name; the rest is relative to the repository root.
  3. 3. What is recorded in history when an Application has several sources?

    All revisions are stored, so a rollback restores the chart and values together.
  4. 4. Which pair of fields must not be used together in one Application?

    They are alternatives: a single source or a list of sources.

Summary

  • spec.sources lets an Application combine several repositories, such as a vendor chart and your own values.
  • A ref source provides files; other sources read them as $ref/path.
  • Each source has its own revision, and history and rollback cover all of them.
  • Keep one Application per deployable unit and be deliberate about which revisions you pin.

Next: Multi-cluster Management