Source types and Helm/Kustomize — directory, repo, helm, kustomize, plugin

The spec.source field names a path the repo server reads. What the repo server does with that path depends on the source type. Argo CD ships with five source types - plain directory, Git repo, Helm chart, Kustomize overlay, and Config Management Plugin - and the renderer determines what inputs the Application accepts and what outputs the controller diffs. Choosing the right source type is one of the high-leverage decisions in an Argo CD deployment.

The five source types

Argo CD’s source types, with the renderer each invokes:

• Directory. Plain YAML manifests under a path. The repo server returns them as-is. The simplest type, right for static manifests with no parameterisation.
• Repo. The same as directory but resolved against a named Git repository. In practice, “repo” and “directory” are the same renderer with the Git origin explicit. Argo CD treats Helm and Kustomize as specialised directory renderers.
• Helm. The repo server detects a Chart.yaml and runs helm template. Values come from values.yaml, named value files (--values), parameter overrides (--set), and file references (--set-file).
• Kustomize. The repo server detects a kustomization.yaml and runs kustomize build. Overlays come from the directory structure; image overrides come from the Application spec.
• Plugin. A Config Management Plugin (CMP) is a sidecar container the repo server invokes to produce manifests. Plugins handle cases the built-in renderers cannot: Jsonnet, CUE, custom tooling.

flowchart LR
    S["spec.source"] --> D["Directory"]
    S --> G["Repo"]
    S --> H["Helm chart"]
    S --> K["Kustomize overlay"]
    S --> P["Config Management Plugin"]
    D --> RS["Repo server: return as-is"]
    G --> RS2["Repo server: clone and return"]
    H --> RH["Repo server: helm template"]
    K --> RK["Repo server: kustomize build"]
    P --> RP["Repo server: invoke plugin sidecar"]

The Application’s source field has optional subfields for Helm and Kustomize that parameterise the render. A plain directory or repo source has no subfields; the renderer is implicit.

Helm sources

A Helm source names a chart path and the value files and parameters to apply:

source:
  repoURL: https://github.com/example/payment-api
  targetRevision: HEAD
  path: helm/payment-api
  helm:
    valueFiles:
      - values-prod.yaml
      - values-region-eu.yaml
    parameters:
      - name: replicaCount
        value: "6"
    releaseName: payment-api

The fields and what they own:

• helm.valueFiles — paths relative to the chart, passed to helm template as --values. Layered in order; later files override earlier ones. Production files are typically per-environment and per-region.
• helm.parameters — key/value pairs passed as --set. Use sparingly; a values file is reviewable in a PR, a parameter override buried in a CRD is not.
• helm.releaseName — overrides the chart’s default release name. Necessary when the same chart renders into the same namespace under different Application names.
• helm.fileParameters — values whose content is read from a file. Use when a value is too large to inline.

flowchart LR
    H["Helm chart"] --> V1["values.yaml"]
    H --> V2["values-prod.yaml"]
    H --> V3["values-region-eu.yaml"]
    H --> P["parameters (--set)"]
    V1 --> T["helm template"]
    V2 --> T
    V3 --> T
    P --> T
    T --> M["Rendered manifests"]

Kustomize sources

A Kustomize source names an overlay path; the overlay’s kustomization.yaml references bases, patches, images, and labels:

source:
  repoURL: https://github.com/example/payment-api
  targetRevision: HEAD
  path: overlays/production
  kustomize:
    images:
      - name: payment-api
        newName: registry.example.com/payment-api
        newTag: v3.4.1
    replicas:
      - name: payment-api
        count: 6
    commonLabels:
      env: prod

The fields and what they own:

• kustomize.images — image overrides applied as kustomize edit set image. The newTag is the production pin; CI bumps this field on each release.
• kustomize.replicas — replica overrides. Useful where HPA is not in play.
• kustomize.commonLabels — labels applied to every resource. Useful for filtering and for Argo CD’s ignoreDifferences.

Plugins and the right time to use one

A Config Management Plugin is a sidecar container the repo server runs as a subprocess. The plugin produces manifests on stdout and Argo CD diffs them. Plugins are the right answer when the source type is something the built-in renderers cannot handle:

• Jsonnet - a templating language with first-class Kubernetes support. Argo CD’s built-in Jsonnet support has limits; a CMP lets the team use the full Jsonnet toolchain.
• CUE - the CUE configuration language. A CUE-based chart produces manifests validated by CUE’s type system.
• Custom tooling - a team that has standardised on a bespoke template language wraps it in a CMP so Argo CD sees the same manifest stream it would for Helm or Kustomize.

The cost is operational: the CMP needs its own image, RBAC to read the source, and installation on every repo server. A plugin is the right answer for a team with a hundred Applications using the same custom template language; it is overkill for three Applications that could be Helm.

Under the hood

The renderer choice changes the failure surface. A plain directory source fails only on YAML syntax errors. A Helm source fails on chart rendering, value file syntax, and value file consistency. A Kustomize source fails on overlay composition, image overrides, and patch validity. A plugin source fails on whatever the plugin fails on, plus the plugin container itself. The same source code can succeed in one renderer and fail in another; the choice of renderer is therefore not a stylistic decision but an operational one.

Production discipline

The rules for production source configuration:

1. Helm value files are versioned in the same repo as the chart. A values-prod.yaml in a separate repo is a change the team cannot trace back to a chart version.
2. Kustomize image overrides pin a digest, not a tag. The newTag field should be a digest (sha256:...) for immutability, not a mutable tag.
3. Plugins are justified per Application. A CMP that exists for a single Application is one the team will forget to maintain. Document the Application set that uses each plugin.
4. The renderer choice is documented in the team’s onboarding guide. New engineers need to know which source type fits which chart.

Cross-course references

• Kubernetes for Production Sysadmins - Parts XXII-XXIII (Helm and Kustomize) cover the rendering pipelines that Argo CD’s sources wrap; the operational differences are there.
• Git, CI/CD & GitOps for Infrastructure Engineers - Part LXXVI-02 (Monorepo with Overlays) is the repository layout this source model implements; source.path points at the overlay.

Quiz