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.
Raw manifest ownership
Section titled “Raw manifest ownership”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 content | How Argo CD detects it | Rendering |
|---|---|---|
| Plain YAML or JSON | A directory with manifest files | Used as is |
| Helm chart | A chart source, or a chart directory in Git | helm template |
| Kustomize | A kustomization.yaml at the source path | Kustomize build |
| Jsonnet | Files with the .jsonnet extension | Native Jsonnet evaluation |
| Anything else | A configured plugin | Config 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.yamlValues can be supplied five ways. When the same key appears in several places, the order of precedence is:
parametersvaluesObjectvalues(a string of YAML)valueFiles- the chart’s own
values.yaml
Why helm ls shows nothing
Section titled “Why helm ls shows nothing”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.
Keeping values in Git
Section titled “Keeping values in Git”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
Section titled “Kustomize”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.yamlEvery base and overlay has a kustomization.yaml that says what to process:
apiVersion: kustomize.config.k8s.io/v1beta1kind: KustomizationnamePrefix: prod- # prepended to metadata.name of every generated resourceresources:- ../../base # import the baseKustomize 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 overrideExtra 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
Section titled “Jsonnet”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.
Config management plugins
Section titled “Config management plugins”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.
Troubleshooting
Section titled “Troubleshooting”| Symptom | Likely cause | Fix |
|---|---|---|
helm ls is empty for a running chart | Argo CD applies rendered manifests, not Helm releases | Expected. Inspect the Application in Argo CD |
| A Helm value is ignored | A higher-precedence source overrides it | Check parameters and valuesObject, which win over values and valueFiles |
| A Kustomize directory is deployed as plain files | No kustomization.yaml at the Application’s path | Point path at the directory that holds kustomization.yaml |
| Kustomize fails to inflate a Helm chart | Helm support is not enabled in the Kustomize build | Set kustomize.buildOptions: --enable-helm and restart Argo CD |
| OCI chart is not found | repoURL includes oci:// or lacks registry credentials | Remove the scheme and register the registry credentials |