Helm & Kustomize with Argo CD · Prasanta Kumar Behera

Use Helm charts and Kustomize overlays through Argo CD: how Argo CD renders them, per-environment values and overlays, values from a separate repo with multiple sources, and promoting a change from dev to prod through Git.

How Argo CD uses Helm and Kustomize

The repo-server detects the source type and renders it into plain manifests:

Helm: rendered like helm template with your values. Argo CD applies and tracks the resources, so helm list shows nothing, and Helm hooks are translated to Argo CD hooks.
Kustomize: rendered like kustomize build.
Plain YAML: used as-is.

A Helm chart is a cake recipe with blanks: "___ eggs, ___ flavour". Values files fill in the blanks for each party (dev, staging, prod). Kustomize is a base cake plus stickers: the same cake, with a different decoration sticker for each party. Either way, the robot bakes the final cake and puts it on the table.

Helm per environment

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: shop-prod
  namespace: argocd
spec:
  project: shop
  source:
    repoURL: https://git.example.com/shop/deploy.git
    targetRevision: main
    path: charts/shop
    helm:
      valueFiles:
        - values.yaml
        - values-prod.yaml          # later files override earlier ones
  destination:
    server: https://kubernetes.default.svc
    namespace: shop-prod

When the chart comes from a chart repository but values live in your Git repo, use multiple sources with a ref:

spec:
  sources:
    - repoURL: https://prometheus-community.github.io/helm-charts
      chart: kube-prometheus-stack
      targetRevision: 65.1.0
      helm:
        valueFiles:
          - $values/platform/monitoring/values-prod.yaml
    - repoURL: https://git.example.com/platform/gitops.git
      targetRevision: main
      ref: values

(Pin chart versions, and read the chart's changelog before bumping; big charts rename values between majors.)

Kustomize overlays

shop/
├── base/
│   ├── deployment.yaml
│   ├── service.yaml
│   └── kustomization.yaml
└── overlays/
    ├── dev/kustomization.yaml
    ├── staging/kustomization.yaml
    └── prod/kustomization.yaml

# overlays/prod/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
namespace: shop-prod
resources:
  - ../../base
images:
  - name: shop
    newName: registry.example.com/shop
    newTag: "1.4.2"
patches:
  - target: { kind: Deployment, name: shop }
    patch: |-
      - op: replace
        path: /spec/replicas
        value: 4

Each environment gets an Application with path: shop/overlays/<env>. Run kustomize build overlays/prod (or kubectl kustomize) in CI to catch errors before Argo CD does.

Promotion through Git

CI builds shop:1.4.2 and updates the dev overlay (a commit, or a PR).
After tests pass in dev, a PR bumps staging; then prod (with a human approval where required).
Each step is a small, reviewable diff; rollback is git revert.

Tools like Argo CD Image Updater, Renovate or a CI job can automate the tag bumps (lesson 07).

Try it: three environments from one base

Build the Kustomize base + dev/staging/prod overlays above for a small app (e.g. nginx or podinfo).
Create three Applications (three namespaces in one kind cluster is fine) pointing at each overlay.
"Release" a new tag to dev only; confirm staging and prod are unchanged; then promote with two more commits.
Deploy a public Helm chart with a values file from your repo using multiple sources.
Run argocd app manifests shop-prod and compare with kustomize build locally.

Going deeper: rendering at scale

Prefer one source of environment truth per app (values files or overlays, not both mixed randomly).
Consider rendered manifests (CI renders Helm/Kustomize into plain YAML committed to an environment branch or folder): reviews show exactly what changes, and Argo CD does less work.
Large Helm charts and many apps load the repo-server; scale its replicas and watch its cache (lesson 07).
Avoid targetRevision: HEAD for third-party charts: pin versions so upgrades are deliberate commits.

Recap

Argo CD renders Helm (like helm template) and Kustomize, then applies and tracks resources itself.
Helm per env: valueFiles; values from another repo: multiple sources with ref and $values/….
Kustomize: base + overlays, one Application per overlay.
Promotion is a sequence of small Git changes; rollback is a revert.

This site is a public version of my personal engineering knowledge hub. It intentionally excludes confidential company information and internal operational details.