Learn GitOps with ArgoCD - Managing Configuration - Helm & Kustomize

#Introduction

So far we've managed plain manifests — great for learning, but not realistic. In the real world, applications use many environments, values change between clusters, and teams share the same chart. That's why you need to master configuration management: ArgoCD doesn't only read a folder full of YAML, it also renders Helm charts, builds Kustomize overlays, and can even evaluate Jsonnet.

Episode 8 closes the basic phase of this series by discussing how ArgoCD uses Helm, Kustomize, plain YAML, Jsonnet, and combinations of them — including Config Management Plugins for custom tooling.

#Helm as the Application Source

If your repository contains a Helm chart, ArgoCD renders it just like running helm template. The Application looks almost the same, only the pointer to the chart is different:

#Values from Git: Values Files

Instead of using --set per parameter, per-environment values are stored as files in the repository — values-prod.yaml, values-staging.yaml, etc. — and referenced via valueFiles. Because these files live in Git, every value change becomes a documented PR.

#Multiple Values Files

To share common values, use several files in order (later files override earlier ones):

Order of values files

spec:
  source:
    helm:
      valueFiles:
        - values-common.yaml
        - values-production.yaml

#Chart from a Helm Repository

ArgoCD can also fetch a chart directly from a Helm repository (not from Git) using the chart + repoURL combination pointing to a chart registry:

Chart from a Helm repository

spec:
  source:
    repoURL: https://charts.example.com
    chart: api
    targetRevision: 2.3.0
    helm:
      valueFiles:
        - values-prod.yaml

#Helm Hooks

ArgoCD understands Helm annotations. Helm hooks (with helm.sh/hook: pre-install, post-install, etc. annotations) are treated by ArgoCD as resource hooks that run in the corresponding sync phase — for example a migration in the PreSync phase.

Tip

Understand the mental model difference: plain Helm manages releases (there's state in the cluster), while ArgoCD manages rendered manifests. With ArgoCD, there's no helm upgrade at runtime — every change goes through Git.

#Kustomize as the Application Source

For Kustomize, ArgoCD runs kustomize build on the folder containing kustomization.yaml:

#Bases and Overlays

This is the recommended pattern: the base stores neutral definitions, per-environment overlays contain the adjustments. ArgoCD just needs to be pointed at the overlay folder — the base/overlays structure built in episode 3 works out of the box.

#Name Prefix/Suffix

Kustomize namePrefix / nameSuffix (e.g. prod-) allows one set of manifests to be used in many environments without name conflicts. ArgoCD renders the final result exactly like a local kustomize build.

#Image Update

With kustomize.images, you can override the image tag without changing Git files:

This is equivalent to kustomize edit set image ghcr.io/arman/api:v1.4.0 — the difference is the change is made directly in the ArgoCD Application.

#Plain YAML Directory

For a folder containing plain YAML, ArgoCD uses it as-is. Some useful options:

Directory options

spec:
  source:
    directory:
      recurse: true
      exclude: "{{.Files}}"

recurse: true — also reads subfolders.
exclude — skips certain files (e.g. templates that aren't ready).
Without options, only .yaml and .yml files at the folder level are read.

#Jsonnet

For teams that like Jsonnet, ArgoCD can evaluate it. Extensions and parameters are provided through the jsonnet field:

Application with a Jsonnet source

spec:
  source:
    path: apps/api
    jsonnet:
      extVars:
        - name: image
          value: ghcr.io/arman/api:v1.4.0
      tlas:
        - code: '{"replicas": 3}'
          name: appConfig

extVars are external variables, tlas are Top-Level Arguments passed to the Jsonnet entrypoint function.

#Combining Helm + Kustomize

This combination is popular: Helm produces the template, Kustomize adjusts it for each environment without changing the chart. In ArgoCD, turn on combined mode with plugin (built-in helm + kustomize):

Helm then Kustomize

spec:
  source:
    repoURL: https://github.com/arman/gitops-lab.git
    path: apps/api
    plugin:
      name: helm-kustomize
      parameters:
        - name: image.tag
          value: v1.4.0
        - name: kustomize.args
          value: overlays/production

#Config Management Plugins (CMP)

The needs are endless — custom templating, internal generators, team tooling. ArgoCD supports Config Management Plugins: container sidecars that render manifests with your own commands. This gives you full freedom to combine any tools in a single render pipeline.

Warning

The Helm + Kustomize pattern requires a CMP properly configured in argocd-repo-server. In the lab, verify with argocd app get api and check the repo-server render errors before assuming the configuration is wrong.

#Closing

The basic phase of this series closes with complete configuration management:

Helm: charts from Git or a registry, parameters, valueFiles, Helm hooks.
Kustomize: base/overlays, namePrefix/nameSuffix, image update without editing Git.
Plain YAML: recurse and exclude for directories.
Jsonnet: extVars and tlas.
Helm + Kustomize via a plugin, and CMP for custom tooling.

Your GitOps foundation is now complete: concepts, installation, operations, sync automation, and configuration management. In episode 9 we'll go beyond a single cluster — multi-cluster management: registering external clusters, hub-and-spoke strategies, and placing applications on many clusters at once. See you there!