How does ArgoCD integrate with Helm, Kustomize, and plain manifests?

Think of ArgoCD's manifest rendering like a universal translator at the United Nations. Delegates speak different languages (Helm charts with values, Kustomize with overlays, plain YAML), but the translator converts everything into one common language (rendered Kubernetes manifests) before the assembly (the cluster) acts on them. The translator does not care which language was spoken — it detects the language automatically and produces the same standard output. This means teams across an organization can each use their preferred templating tool while ArgoCD provides a consistent GitOps workflow for all of them.

ArgoCD detects the manifest source type automatically based on the repository contents. If it finds a Chart.yaml file, it treats the source as a Helm chart. If it finds a kustomization.yaml or kustomization.yml file, it uses Kustomize. If neither is present, it treats the directory as plain YAML manifests and applies all YAML and JSON files found in the specified path. You can also explicitly set the source type in the Application spec to override auto-detection. For Helm, you can specify values files, inline value overrides, release name, and chart version. For Kustomize, you can override images, add name prefixes and suffixes, and set common labels and annotations. For plain manifests, ArgoCD supports recursive directory traversal and file include or exclude patterns using the directory.recurse and directory.exclude options.

Internally, the Repository Server is the component responsible for all manifest rendering. When the Application Controller requests the desired state for an application, the Repository Server clones the Git repository (or fetches from a Helm chart repository), caches the result, and invokes the appropriate rendering tool. For Helm, it runs the equivalent of helm template with the configured values, producing raw Kubernetes manifests without installing a release into the cluster — this is a critical distinction because ArgoCD does not use Tiller or the Helm release secret mechanism. For Kustomize, it runs kustomize build on the specified path. The rendered output is then returned to the Application Controller for diffing against the live state. The Repository Server maintains a cache of cloned repositories and rendered manifests with configurable TTL, reducing Git API calls and rendering overhead for frequently polled applications.

In production, organizations commonly use a hybrid approach. Infrastructure components like cert-manager, ingress-nginx, and monitoring stacks are deployed as Helm charts sourced directly from public or private Helm repositories using the helm source type with a repoURL pointing to the chart repository. Application teams use Kustomize with a base-and-overlay pattern where the base directory contains the core Deployment, Service, and ConfigMap definitions, and overlays for staging and production add environment-specific patches like replica counts, resource limits, and ingress hostnames. Some teams use Helm charts as Kustomize bases by running helm template in a CI pipeline and committing the rendered output, giving them the parameterization power of Helm with the patching flexibility of Kustomize. This multi-tool strategy allows each team to use the approach that best fits their workflow while ArgoCD provides a unified deployment and observability layer.

A major gotcha with Helm integration is that ArgoCD runs helm template, not helm install, which means Helm hooks and lookup functions behave differently. The lookup function always returns empty results because there is no live cluster context during template rendering, causing templates that depend on runtime lookups to produce incorrect manifests. Helm release lifecycle hooks like pre-install and post-install are not natively supported — you must use ArgoCD sync hooks instead. Another common pitfall with Kustomize is version mismatches; ArgoCD bundles a specific version of Kustomize, and if your kustomization.yaml uses features from a newer version, rendering will fail silently or produce unexpected output. Teams should pin the Kustomize version in ArgoCD's configmap or use a custom plugin to ensure compatibility. For plain manifests, engineers frequently forget that ArgoCD applies all YAML files in the directory and accidentally include test fixtures or documentation YAML files in the deployment path.