Skip to content
Tutorials Center
My learning

Topics

Lesson 19 of 37 ยท Helm, Kustomize and Config Management

Helm Charts in Argo CD

Deploy Helm charts with Argo CD: chart sources, valueFiles, inline values, parameters, hooks, OCI registries, and how Argo CD differs from helm install.

Helm is the most common way to package Kubernetes applications, and Argo CD supports it directly. You do not run helm install. Instead, you describe a chart and its values in an Application, and Argo CD renders the chart, compares the result with the cluster and applies the difference.

This lesson shows the Helm-specific fields of an Application, the order in which values are merged, and the few places where Argo CD behaves differently from the Helm CLI.

How Argo CD uses Helm

Argo CD uses Helm only as a template engine. The repo server runs the equivalent of helm template and hands the resulting manifests to the sync engine. Consequences:

  • There is no Helm release in the cluster. helm list shows nothing for an application deployed by Argo CD, and there are no release Secrets.
  • helm rollback and helm upgrade are not used. Rollback means going back to an earlier Git revision (see the other lessons on sync).
  • Chart hooks are translated to Argo CD hooks. For example helm.sh/hook: pre-install and pre-upgrade become PreSync, and post-install and post-upgrade become PostSync.
  • .Release.Name is the application name unless you set releaseName. .Release.Namespace is the destination namespace. .Capabilities reflects the target cluster.
flowchart LR
  G["Git repo or chart repo"] --> R["repo server: helm template"]
  V["valueFiles, values, parameters"] --> R
  R --> M["Rendered manifests"]
  M --> C["Application controller: diff and sync"]
  C --> K["Cluster"]

Helm renders; Argo CD owns the diff and apply.

A chart that lives in Git

When the chart is in your own repository, path points at the folder that contains Chart.yaml:

YAML
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: shop-web
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://git.example.com/platform/shop.git
    targetRevision: main
    path: charts/web
    helm:
      releaseName: shop-web
      valueFiles:
        - values.yaml
        - values-prod.yaml
      parameters:
        - name: image.tag
          value: "2.8.1"
  destination:
    name: in-cluster
    namespace: shop
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true

valueFiles paths are relative to path. A file that does not exist makes the render fail, unless you set ignoreMissingValueFiles: true, which is handy for optional per-environment files.

A chart from a Helm repository or OCI registry

For a published chart, chart replaces path, and targetRevision is a chart version:

YAML
source:
  repoURL: https://charts.example.org/stable
  chart: nginx-gateway
  targetRevision: 1.4.*        # a semver range is allowed
  helm:
    valuesObject:
      replicaCount: 3

OCI registries use an oci:// URL without a scheme path for the chart name:

YAML
source:
  repoURL: registry.example.com/charts
  chart: web
  targetRevision: 0.9.2

Register the repository (with credentials, when private) under Settings > Repositories or as a declarative Secret. Pin an exact version in production: a range such as 1.4.* lets the deployed manifests change without any commit in your repository.

The three ways to set values

Field Form Typical use
valueFiles list of files in the repo Shared defaults and environment files
values / valuesObject inline YAML (string / structured) A few overrides kept next to the Application
parameters list of name / value Single keys, often image tags set by CI

fileParameters also exists and maps a parameter name to a file's contents, like --set-file.

Precedence. Argo CD builds the command in this order, and the last one wins: all valueFiles (in list order), then the inline values, then parameters (and file parameters). So a parameter beats an inline value, which beats a value file, which beats the chart's own values.yaml.

Prefer valuesObject over values: it is structured YAML, so editors validate it and tools like Kustomize patches or ApplicationSet templates can merge into it, while values is one opaque string.

Python Stand-in: value precedence in Argo CD

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Run it, then remove the parameter and watch replicaCount fall back to 4. The model is a teaching aid, not Helm itself; it shows the order, not every edge case.

Rendering details that surprise people

  • helm template has no cluster access, so the lookup function returns empty. Charts that depend on lookup to preserve generated passwords will regenerate them on every render and show permanent drift.
  • Random values (randAlphaNum) change on each render and cause an endless OutOfSync. Generate secrets outside the chart (see Secrets in GitOps).
  • CRDs in a chart's crds/ folder are installed; set skipCrds: true when the cluster manages them separately.
  • Kubernetes version: Argo CD passes the cluster's version and API list to Helm so .Capabilities checks work. You can override it per application with kubeVersion and apiVersions under helm.
  • Helm test hooks are ignored by default.

Keep a committed values-<env>.yaml per environment and let parameters carry only what CI changes (usually the image tag). Reviewers then see the full intent in Git.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does Argo CD run to turn a Helm chart into manifests?

    Argo CD only renders the chart; it applies the resulting manifests itself, so no Helm release exists.
  2. 2. Which source has the highest precedence when the same key is set several ways?

    Parameters are passed last, like --set, so they override value files and inline values.
  3. 3. Which field points an Application at a chart published in a chart repository?

    chart names the chart and targetRevision is its version; path is for charts stored in Git.
  4. 4. Why can random-value chart templates cause trouble with Argo CD?

    The desired state changes on every refresh, so it never matches the live state.

Summary

  • Argo CD renders Helm charts with helm template; there is no Helm release, and hooks map to Argo CD hooks.
  • Use path for charts in Git and chart plus a version for chart repositories and OCI registries.
  • Values merge in this order, last wins: valueFiles, inline values/valuesObject, parameters.
  • Avoid lookup and random generators; pin chart versions.

Next: Kustomize in Argo CD