Skip to content
Documentation Background

Rendering tools

Argo CD does not deploy templates. The repo server turns every source into plain Kubernetes manifests, and only those manifests are compared with the cluster and applied. Helm, Kustomize, Jsonnet, and custom plugins all exist so that teams avoid copying YAML between environments, and they all end at the same raw-manifest boundary.


Argo CD works with raw Kubernetes manifests and keeps full visibility of each object. It does not hand release tracking to another tool. Whatever generates the YAML, Argo CD evaluates, diffs, and applies the final objects itself.

Source contentHow Argo CD detects itRendering
Plain YAML or JSONA directory with manifest filesUsed as is
Helm chartA chart source, or a chart directory in Githelm template
KustomizeA kustomization.yaml at the source pathKustomize build
JsonnetFiles with the .jsonnet extensionNative Jsonnet evaluation
Anything elseA configured pluginConfig management plugin

This page covers how Argo CD uses each tool, with a short primer where the tool needs one.


Argo CD uses Helm only to inflate charts. It runs the equivalent of helm template <options> and applies the output, and the lifecycle of the application belongs to Argo CD, not to Helm. Charts can come from a Helm repository, an OCI registry, or a directory in Git.

spec:
source:
repoURL: https://charts.example.com
chart: web-app
targetRevision: 1.4.0
helm:
releaseName: web-app # name passed to helm template
parameters: # like helm --set
- name: image.tag
value: "1.4.0"
valuesObject: # inline values, like a values file
resources:
limits:
memory: 256Mi
valueFiles: # values files from the chart or repo
- values-prod.yaml

Values can be supplied five ways. When the same key appears in several places, the order of precedence is:

  1. parameters
  2. valuesObject
  3. values (a string of YAML)
  4. valueFiles
  5. the chart’s own values.yaml

A Helm release exists only because helm install or helm upgrade wrote release Secrets into the cluster. Argo CD never runs those commands, so there are no release Secrets, and helm ls -n <namespace> lists nothing even though the Pods and Services are running. The trade-off is a benefit: because Argo CD holds the rendered manifests, it can diff a Helm application against live state like any other.

A chart from a public repository can take its values from a separate private Git repository by using multiple sources with a ref. See Applications.


Kustomize patches Kubernetes manifests without editing the originals. As an application spreads across environments, clusters, and regulatory boundaries, copies of the same YAML multiply. Kustomize stores only the differences as deltas, which keeps the base manifests unchanged and fits the immutability principle of GitOps.

Manifests are organized in directories:

  • Bases - directories of common manifests that describe the baseline for every deployment
  • Overlays - one directory per environment (dev, staging, prod) that imports a base and patches it, for example replicas, environment variables, or image tags

Overlays can build on other bases and overlays, and can reference remote Git repositories.

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

Every base and overlay has a kustomization.yaml that says what to process:

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
namePrefix: prod- # prepended to metadata.name of every generated resource
resources:
- ../../base # import the base

Kustomize is built into kubectl (kubectl apply -k <dir> and kubectl kustomize). In Argo CD, if a kustomization.yaml exists at the Application’s repoURL and path, Argo CD renders the directory with Kustomize automatically. An Application can override a few settings without touching the files:

spec:
source:
repoURL: https://git.example.com/org/config.git
targetRevision: main
path: app/overlays/prod
kustomize:
namePrefix: prod-
images:
- registry.example.com/web:1.4.2 # image override

Extra arguments for kustomize build go in the kustomize.buildOptions key of the argocd-cm ConfigMap. Restart Argo CD after changing it.

Kustomize can also inflate a Helm chart, so overlays can sit on top of a rendered chart. That needs the --enable-helm flag, set either through kustomize.buildOptions: --enable-helm globally or in a custom plugin.


Jsonnet is a JSON templating language that Argo CD supports natively. It parses files with the .jsonnet extension in the source and converts them to Kubernetes objects. No third-party binary or plugin declaration is needed.


A tool that Argo CD does not support natively, such as Cue or an internal generator, can be added through a config management plugin. Plugins remove any limit on how manifests are produced while Argo CD still handles deployment and drift tracking. Their output is treated like any other: raw manifests that Argo CD applies.


SymptomLikely causeFix
helm ls is empty for a running chartArgo CD applies rendered manifests, not Helm releasesExpected. Inspect the Application in Argo CD
A Helm value is ignoredA higher-precedence source overrides itCheck parameters and valuesObject, which win over values and valueFiles
A Kustomize directory is deployed as plain filesNo kustomization.yaml at the Application’s pathPoint path at the directory that holds kustomization.yaml
Kustomize fails to inflate a Helm chartHelm support is not enabled in the Kustomize buildSet kustomize.buildOptions: --enable-helm and restart Argo CD
OCI chart is not foundrepoURL includes oci:// or lacks registry credentialsRemove the scheme and register the registry credentials