Helm

Deploy Helm charts with Argo CD

Argo CD uses Helm only to inflate charts with helm template. The application lifecycle is managed by Argo CD instead of Helm. This means Helm commands like helm ls won’t show applications deployed by Argo CD.

Basic Helm Chart Application

Deploy a Helm chart from a chart repository:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: sealed-secrets
  namespace: argocd
spec:
  project: default
  source:
    chart: sealed-secrets
    repoURL: https://bitnami-labs.github.io/sealed-secrets
    targetRevision: 1.16.1
    helm:
      releaseName: sealed-secrets
  destination:
    server: "https://kubernetes.default.svc"
    namespace: kubeseal

OCI Helm Charts

Deploy charts from OCI registries:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: nginx
spec:
  project: default
  source:
    chart: nginx
    repoURL: registry-1.docker.io/bitnamicharts
    targetRevision: 15.9.0
  destination:
    name: "in-cluster"
    namespace: nginx

Don’t include the oci:// prefix in the repoURL for OCI registries.

Values Files

Specify one or more values files:

source:
  helm:
    valueFiles:
      - values-production.yaml
      - values-optional-override.yaml
    ignoreMissingValueFiles: true

valueFiles · array

List of values files relative to the Helm chart location

ignoreMissingValueFiles · boolean

Ignore missing values files instead of erroring. Useful for default/override patterns with ApplicationSets.

Starting with v2.6, values files can be sourced from a separate repository using multiple sources.

Values Object

Provide values directly in the Application manifest:

source:
  helm:
    valuesObject:
      ingress:
        enabled: true
        path: /
        hosts:
          - mydomain.example.com
        annotations:
          kubernetes.io/ingress.class: nginx
          kubernetes.io/tls-acme: "true"
        tls:
          - secretName: mydomain-tls
            hosts:
              - mydomain.example.com

Values String

Alternatively, pass values as a YAML string:

source:
  helm:
    values: |
      ingress:
        enabled: true
        path: /
        hosts:
          - mydomain.example.com

Parameters

Override specific values:

source:
  helm:
    parameters:
      - name: "service.type"
        value: LoadBalancer
      - name: "image.tag"
        value: "v1.2.3"

parameters · array

List of parameter name/value pairs to override Helm values

Value Precedence

Values are merged with the following precedence (highest to lowest):

1. parameters (highest)
2. valuesObject
3. values
4. valueFiles
5. Chart’s default values.yaml (lowest)

When multiple valueFiles are specified, the last file has highest precedence.

File Parameters

Set values from file contents:

source:
  helm:
    fileParameters:
      - name: some.key
        path: path/to/file.ext

Release Name

Override the default release name (which equals the Application name):

source:
  helm:
    releaseName: myRelease

Overriding release name may cause issues if the chart uses the app.kubernetes.io/instance label, since Argo CD uses the Application name for tracking. Configure application.instanceLabelKey in argocd-cm to use a different label.

Helm Hooks

Argo CD supports most Helm hooks by mapping them to Argo CD hooks:

Helm Hook	Argo CD Equivalent
helm.sh/hook: crd-install	Normal CRD handling
helm.sh/hook: pre-install	argocd.argoproj.io/hook: PreSync
helm.sh/hook: pre-upgrade	argocd.argoproj.io/hook: PreSync
helm.sh/hook: post-install	argocd.argoproj.io/hook: PostSync
helm.sh/hook: post-upgrade	argocd.argoproj.io/hook: PostSync
helm.sh/hook: pre-delete	argocd.argoproj.io/hook: PreDelete
helm.sh/hook: post-delete	argocd.argoproj.io/hook: PostDelete

If you define any Argo CD hooks, ALL Helm hooks will be ignored. Argo CD cannot distinguish between “install” and “upgrade” - every operation is a “sync”.

Hook Best Practices

• Make hooks idempotent
• Annotate pre-install and post-install with hook-weight: "-1"
• Annotate pre-upgrade and post-upgrade with hook-delete-policy: before-hook-creation

Random Data

Helm charts using randAlphaNum will cause perpetual OutOfSync status. Override with explicit values:

argocd app set redis -p password=abc123

Build Environment

Access build environment variables in parameters:

spec:
  source:
    helm:
      parameters:
        - name: app
          value: $ARGOCD_APP_NAME
        - name: revision
          value: $ARGOCD_APP_REVISION

Helm Plugins

Install custom Helm plugins via custom image or initContainers. Example with initContainer:

repoServer:
  env:
    - name: HELM_CACHE_HOME
      value: /helm-working-dir
    - name: HELM_CONFIG_HOME
      value: /helm-working-dir
    - name: HELM_DATA_HOME
      value: /helm-working-dir
  initContainers:
    - name: helm-gcp-authentication
      image: alpine/helm:3.16.1
      volumeMounts:
        - name: helm-working-dir
          mountPath: /helm-working-dir
      command: ["/bin/sh", "-c"]
      args:
        - |
          helm plugin install https://github.com/hayorov/helm-gcs.git;
          chmod -R 777 $HELM_DATA_HOME;

Additional Options

version · string

Helm version to use (v2 or v3). Defaults to v3.

passCredentials · boolean

Pass repository credentials for charts from different domains (Helm 3.6.1+)

skipCrds · boolean

Skip CRD installation

skipSchemaValidation · boolean

Skip values schema validation

skipTests · boolean

Skip test manifests during template rendering

CLI Examples

# Set values file
argocd app set helm-guestbook --values values-production.yaml

# Set parameter
argocd app set helm-guestbook -p service.type=LoadBalancer

# Set file parameter
argocd app set helm-guestbook --helm-set-file some.key=path/to/file.ext

# Set release name
argocd app set helm-guestbook --release-name myRelease

# Set Helm version
argocd app set helm-guestbook --helm-version v3