Using Helm Charts with Argo CD | Production-Ready Setup Tutorial

This comprehensive guide explores how to integrate Helm charts into an Argo CD GitOps workflow. It bridges the gap between Helm's powerful templating and configuration capabilities at scale, and Argo CD's automated, declarative application lifecycle management.

1. Why Do We Need Helm with Argo CD? (The Status Quo)

When managing Kubernetes applications at scale, engineering teams often face a dilemma:

• Pure Plain YAML: Great for simple setups, but becomes extremely repetitive when managing multiple environments (dev, staging, production) or large parameter sets.
• Standalone Helm: Provides powerful templating (values.yaml, charts) and packaging, but relies on imperative operational commands (helm install, helm upgrade, helm rollback) executed manually or via CI/CD pipelines, which breaks pure GitOps principles.

Real-Life Analogy: The Blueprint Printer vs. The Construction Crew

Think of Helm as an architect's blueprint-rendering machine that takes customizable parameters (values.yaml) and generates standard building blueprints (Kubernetes manifests). Think of Argo CD as the general contractor and automated construction crew. Argo CD does not design the building; it takes the blueprints produced by Helm, inspects the actual building site (the Kubernetes cluster), and automatically pours concrete and erects steel until the live site matches the blueprint.

2. Core Mental Model: How Argo CD Interacts with Helm

When you configure an Argo CD application to point to a Helm chart repository or Git directory containing a Helm chart, Argo CD does not use Helm as a deployment engine.

• No Helm Lifecycle Ownership: Argo CD never executes helm install, helm upgrade, or helm rollback.
• Manifest Rendering Tool Only: Under the hood, Argo CD leverages Helm as a template-generation engine by executing the helm template command.

The Under-the-Hood Rendering & Deployment Flow

Git Repository (Helm Chart + values.yaml)
   |
   | pulled by Argo CD Repository Server
   v
Argo CD executes `helm template` command under the hood
   |
   | generates raw Kubernetes manifests (Deployment, Service, ConfigMap, Namespace)
   v
Argo CD Application Controller picks up rendered manifests
   |
   | applies manifests to Kubernetes API Server
   v
Live Cluster State (Synced & Reconciled)

3. Architecture Breakdown: Repository Server vs. Application Controller

In the Argo CD architecture, two core components handle the Helm integration workflow:

Post-Render Behavior

Once Argo CD renders the Helm chart into raw Kubernetes manifests during the sync phase, Helm is completely out of the picture. All subsequent operations—such as monitoring health, tracking drift, rolling back changes, and pruning deleted resources—are performed natively by Argo CD using Git as the single source of truth.

4. Why Use Helm If Argo CD Manages the Lifecycle?

A common question is: If Argo CD handles deployment, rollbacks, and synchronization, why do we still need Helm?

• Simplifying Massive YAML Files: Production applications comprise dozens of interconnected resources (Deployments, Services, ConfigMaps, Secrets, Ingresses). Editing individual fields across raw manifests is error-prone. Helm centralizes variables into values.yaml.
• Multi-Environment Configuration at Scale: Instead of maintaining three separate copies of raw manifests for dev, stage, and prod, you maintain one chart and swap out values files (values-dev.yaml, values-prod.yaml).
• Industry Standard for Packaging: Most enterprise-grade, third-party applications (databases, ingress controllers, service meshes) are distributed as Helm charts. Integrating them into Argo CD requires native chart support.

5. Directory Structure for the Demo

To implement a Helm-backed Argo CD setup, organize your project repository into dedicated Helm and Argo manifests directories:

6. Step-by-Step Implementation

Step 1: Examine the Helm Templates and Values

In your Helm chart's templates/ directory, templates reference variables defined in values.yaml. For example, in service.yaml:

apiVersion: v1
kind: Service
metadata:
  name: {{ .Release.Name }}-service
  namespace: {{ .Values.app.namespace }}
spec:
  type: {{ .Values.service.type }}
  ports:
    - port: {{ .Values.service.port }}
      targetPort: {{ .Values.service.port }}
  selector:
    app: {{ .Release.Name }}

Step 2: Create the Argo CD Application Manifest (app1-app.yaml)

Define the Argo CD application Custom Resource, instructing Argo CD where to locate the Helm chart, which release name to use, and how to synchronize.

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: app1
  namespace: argocd
spec:
  project: default
  source:
    repoURL: 'https://github.com/your-username/your-repo.git'
    targetRevision: HEAD
    path: app1-helm
    helm:
      releaseName: app1
      # valuesFiles:
      #   - values.yaml
  destination:
    server: 'https://kubernetes.default.svc'
    namespace: app1-ns
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true

Note: If you omit the helm.releaseName block in the Argo CD application spec, Argo CD will automatically use the Argo CD application name (app1) as the Helm release name. Specifying helm.releaseName explicitly gives you precise control over release naming conventions.

Step 3: Deploy the Argo CD Application CRD

Apply the application manifest to your cluster using kubectl:

kubectl apply -f argo/app1-app.yaml

Step 4: Register the Repository in Argo CD

1. Access your Argo CD UI via browser/port-forwarding (localhost:8080).
2. Navigate to Settings -> Repositories -> Connect Repo.
3. Add your Git repository URL (configured as public or authenticated).
4. Upload or commit your app1-helm directory and values.yaml to the root of your Git repository.

7. Verification and Port Forwarding Walkthrough

Once Argo CD detects the repository changes (or after clicking Refresh on the UI dashboard), Argo CD will execute the internal helm template command, render the manifests, and sync them to the cluster.

Accessing the Deployed Application

To verify that the application is running successfully inside the app1-ns namespace, forward traffic from your local machine to the Kubernetes Service:

kubectl port-forward -n app1-ns service/app1-service 8081:80

Open your browser and navigate to:

http://localhost:8081

(Expected response: "Welcome to cloud with VJOS, your happy place for cloud and DevOps learning.")

8. Summary and Key Takeaways

• Helm as a Renderer: Argo CD uses Helm strictly as a manifest rendering tool via helm template, not as a deployment engine.
• No Native Helm Commands: Operational commands like helm install, helm upgrade, and helm rollback are bypassed; all lifecycle management is handled natively by Argo CD.
• Repository Server Role: The Argo CD Repository Server fetches Helm charts from Git and processes templates using configured parameters and values files.
• Application Controller Reconciliation: The Application Controller applies rendered manifests to the Kubernetes API server and continuously enforces desired state.
• Simplifying Production Config: Helm values.yaml files eliminate repetitive YAML duplication, making multi-environment management scalable and clean.
• GitOps Single Source of Truth: Combining Helm with Argo CD delivers the templating power of Helm alongside the automated synchronization, drift correction, pruning, and self-healing of GitOps.