Installing Argo CD with Helm: Production Values, HA, Upgrades and Rollback

Installing Argo CD

This guide treats the argocd Helm chart as a controlled platform release. It uses the official argo/argo-cd chart, keeps configuration in a reviewable values file, separates installation from validation, and makes recovery a planned workflow rather than an improvised helm rollback. It is about installing Argo CD itself with Helm—not about using Argo CD to render Helm charts for applications.

#Context

The official chart currently requires Helm 3 and a supported Kubernetes

Start by deciding who owns four things:

• The Helm release: the team permitted to change chart version and values.
• Argo CD CRDs: either the chart or a separate cluster-level lifecycle, never an ambiguous mixture.
• Secrets and identity: an external secret workflow, SSO configuration and break-glass procedure.
• Ingress and certificates: including whether TLS terminates at Argo CD, at the ingress controller, or at both layers.

The chart defaults are a starting point, not a production recommendation. The upstream Argo CD documentation describes non-HA installation as suitable for evaluation rather than production. The HA design adds replicas and Redis HA, and its anti-affinity model needs at least three schedulable nodes. A small cluster that cannot satisfy those constraints is not made highly available by setting replica counts to two.

#Architecture

Argo CD is largely stateless. Desired configuration and application state live in Kubernetes objects stored by etcd; Redis is a disposable cache. That does not make every component interchangeable. The application controller reconciles desired and actual state, the repository server fetches sources and generates manifests, the API server serves the UI and CLI, and Redis absorbs cache and coordination work.

The official chart’s HA example enables redis-ha, keeps one application-controller replica, and uses two replicas for the API server, repository server and ApplicationSet controller. Redis HA enforces separation across nodes, which is why the three-node prerequisite matters. Use topology spread constraints or anti-affinity that match real failure domains; three pods on three virtual machines sharing one physical host or one availability-zone dependency do not provide the resilience the values file implies.

For a deeper treatment of reconciliation pressure after installation, see Taming Argo CD Sync Storms in Shared Clusters. This guide stops at establishing a safe control plane and does not duplicate its ApplicationSet, cache, sharding or rate-limit analysis.

#Implementation

Use an explicit working directory in version control with a values file, a short decision record and a captured render. The following shell variables are placeholders; replace them from an approved change record rather than copying a version from an article:

1export ARGOCD_NAMESPACE="argocd"
2export ARGOCD_RELEASE="argocd"
3export ARGOCD_CHART_VERSION="<approved-chart-version>"
4
5helm repo add argo https://argoproj.github.io/argo-helm
6helm repo update
7helm search repo argo/argo-cd --versions
8helm show chart argo/argo-cd --version "$ARGOCD_CHART_VERSION"
9helm show values argo/argo-cd --version "$ARGOCD_CHART_VERSION" > upstream-values.yaml

Review the chart metadata and changelog before building values-production.yaml. Keep that file focused on deliberate overrides. Copying the entire upstream values file hides which settings the team actually owns and makes future default changes difficult to assess.

1global:
2  domain: argocd.example.com
3
4controller:
5  replicas: 1
6  resources:
7    requests:
8      cpu: 250m
9      memory: 512Mi
10    limits:
11      memory: 1Gi
12
13server:
14  replicas: 2
15  pdb:
16    enabled: true
17    minAvailable: 1
18  ingress:
19    enabled: true
20    ingressClassName: nginx
21    tls: true
22
23repoServer:
24  replicas: 2
25  pdb:
26    enabled: true
27    minAvailable: 1
28  resources:
29    requests:
30      cpu: 250m
31      memory: 512Mi
32    limits:
33      memory: 1Gi
34
35applicationSet:
36  replicas: 2
37
38redis-ha:
39  enabled: true
40
41configs:
42  params:
43    server.insecure: false

This is a structural example, not a universal production file. Confirm every key against the pinned chart’s own values.yaml. Resource requests must come from measured workload and cluster capacity. Ingress TLS settings depend on the chosen termination design: if an ingress controller terminates TLS and forwards HTTP, Argo CD’s server configuration differs from TLS passthrough. Avoid combining snippets from different ingress modes.

Before a state-changing installation, render locally and inspect the result:

1helm lint argo/argo-cd 
2  --version "$ARGOCD_CHART_VERSION" 
3  --values values-production.yaml
4
5helm template "$ARGOCD_RELEASE" argo/argo-cd 
6  --version "$ARGOCD_CHART_VERSION" 
7  --namespace "$ARGOCD_NAMESPACE" 
8  --values values-production.yaml 
9  > rendered-argocd.yaml
10
11kubectl apply --dry-run=server -f rendered-argocd.yaml

Inspect cluster-scoped RBAC, CRDs, NetworkPolicies, Services, ingress resources, security contexts and secret references in the render. A server-side dry run is valuable because it exercises admission and API compatibility, but it is not proof that the deployment will become healthy.

When the review gate passes, the controlled change is:

1helm upgrade --install "$ARGOCD_RELEASE" argo/argo-cd 
2  --version "$ARGOCD_CHART_VERSION" 
3  --namespace "$ARGOCD_NAMESPACE" 
4  --create-namespace 
5  --values values-production.yaml 
6  --atomic 
7  --timeout 10m

--atomic asks Helm to roll back a failed upgrade, but it cannot decide whether an externally managed CRD change, identity-provider change or secret rotation is safe to reverse. Keep the pre-change evidence and manual recovery plan even when atomic rollback is enabled.

#Validation

Validation should prove the release, Kubernetes workloads and Argo CD behaviour independently. Record commands and observed output in the change evidence rather than declaring success because Helm returned exit code zero.

1. Confirm helm status and helm history show the expected chart revision and version.
2. Check Deployments and StatefulSets have the intended ready replicas and are distributed across the expected nodes or zones.
3. Inspect PodDisruptionBudgets and verify they permit maintenance without allowing every replica to disappear.
4. Review events for scheduling failures, rejected security contexts, missing secrets, failed mounts and readiness probe errors.
5. Test the external hostname, certificate chain, redirect behaviour and CLI/API connectivity.
6. Verify SSO and RBAC with a least-privileged account, then test the documented break-glass path without leaving the default administrator as routine access.
7. Register a non-production repository and reconcile a harmless test Application. Confirm comparison, sync, health assessment and audit events.
8. Confirm metrics are scraped and alerts exist for unavailable replicas, reconciliation backlog, repository-server failures and Redis health.

1helm status "$ARGOCD_RELEASE" -n "$ARGOCD_NAMESPACE"
2helm history "$ARGOCD_RELEASE" -n "$ARGOCD_NAMESPACE"
3kubectl get deploy,statefulset,pod,pdb -n "$ARGOCD_NAMESPACE" -o wide
4kubectl get events -n "$ARGOCD_NAMESPACE" --sort-by=.lastTimestamp
5kubectl wait --for=condition=Available deployment/argocd-server 
6  -n "$ARGOCD_NAMESPACE" --timeout=5m

Adapt resource names to the release naming produced by the pinned chart. A wait on the API server alone is insufficient: it does not test repository generation, controller reconciliation or Redis behaviour.

#Failure Modes

Pods remain Pending. HA anti-affinity may be unsatisfiable, requests may exceed available capacity, or required topology labels may be absent. Read scheduler events before weakening the rule. If the cluster cannot provide the failure domains, record that HA is unavailable rather than disguising a single-domain installation.

The UI is reachable but login or CLI calls loop or fail. Check the chosen TLS termination mode, forwarded protocol headers, Argo CD’s insecure-server setting and the public URL configured for SSO. Do not toggle several ingress annotations at once; render one coherent upstream-supported pattern.

Repository generation is slow or OOMKilled. The repository server executes Helm, Kustomize and plugins, and uses temporary disk while processing repositories. Inspect memory, CPU, /tmp capacity and manifest-generation latency. Scaling replicas may improve concurrency, while unconstrained concurrency can increase memory pressure.

An upgrade fails around CRDs. Establish ownership first. Current chart releases can install and upgrade templated CRDs, while older chart layouts and externally managed CRDs require a separate server-side update. Never assume helm rollback restores a CRD schema or converts existing custom resources back to an earlier representation.

Redis HA cannot form a healthy group. Confirm all Redis and HAProxy pods, authentication secret, anti-affinity placement and network policy paths. Redis is a cache, but an unavailable cache tier still disrupts the control plane. Do not restore service by deleting secrets or disabling authentication without understanding the chart’s secret-init lifecycle.

#Security

Argo CD is a privileged deployment system. Treat its API, repository credentials and Kubernetes identities as control-plane assets. Prefer SSO with group-to-role mapping, narrowly scoped projects and explicit destination/repository allow-lists. Disable routine use of the local administrator after the recovery path is tested, and keep emergency credentials in an audited secret system.

Review the chart’s container and pod security contexts rather than replacing them wholesale. Current defaults include non-root execution and dropped Linux capabilities for several components, but overlays, plugins and init containers can change the effective posture. Admission policy output from the rendered manifests is part of the security review.

Enable NetworkPolicies only when the cluster networking implementation enforces them and the required flows are understood. Verify DNS, Kubernetes API, repository, identity-provider, metrics and ingress paths. A default-deny policy that silently blocks repository access is not safer than an open policy with no review; the safe outcome is a tested, documented allow-list.

Do not put repository passwords, client secrets or bcrypt hashes in a shared values file. Reference pre-created Kubernetes Secrets or an approved external-secrets mechanism. The chart README specifically warns that, when Argo CD manages its own chart, dollar characters in a bcrypt hash can be altered if the value is passed through Helm parameters rather than a values block.

#Recovery

Before an upgrade, capture the existing release history, deployed values, chart metadata, Argo CD configuration objects and the health of a representative Application. Read every intervening Argo CD upgrade note when crossing minor versions and every highlighted chart changelog entry between the installed and target chart releases.

1helm history "$ARGOCD_RELEASE" -n "$ARGOCD_NAMESPACE"
2helm get values "$ARGOCD_RELEASE" -n "$ARGOCD_NAMESPACE" -o yaml 
3  > before-values.yaml
4helm get manifest "$ARGOCD_RELEASE" -n "$ARGOCD_NAMESPACE" 
5  > before-manifest.yaml
6
7helm diff upgrade "$ARGOCD_RELEASE" argo/argo-cd 
8  --version "$ARGOCD_CHART_VERSION" 
9  --namespace "$ARGOCD_NAMESPACE" 
10  --values values-production.yaml

The diff plugin is optional and must itself be approved in controlled environments. Without it, compare deterministic helm template output against the captured manifest. Pay particular attention to immutable fields, selectors, Service changes, RBAC, NetworkPolicies, CRDs and any resource that will be recreated.

If an upgrade degrades the release, stop further changes and classify the failure. A workload-only regression may be recoverable with a Helm revision rollback:

1helm rollback "$ARGOCD_RELEASE" <known-good-revision> 
2  --namespace "$ARGOCD_NAMESPACE" 
3  --wait 
4  --timeout 10m

That command changes cluster state and needs the same approval and validation as an upgrade. If the change included CRDs, external secrets, SSO registrations or certificate rotation, restore those components according to their own recovery plans. After rollback, repeat the functional Application test; healthy pods alone do not prove reconciliation is restored.

#Verified sources

• Argo Project: Argo CD Helm chart README — prerequisites, installation, HA examples, ingress patterns, CRD lifecycle and chart upgrade notes.
• Argo Project: Argo CD chart values — the authoritative configuration surface for the current chart branch.
• Argo CD installation guidance — installation modes and the production HA recommendation.
• Argo CD high-availability guidance — component responsibilities, node requirements and scaling constraints.
• Argo CD upgrade guidance — breaking-change review, version transitions and backup expectations.

#Operate the release as a controlled system

A production-ready Argo CD Helm installation is not defined by a successful install command. It is defined by a pinned and reviewable release, explicit CRD and secret ownership, topology that matches real failure domains, evidence that the control plane can reconcile an application, and a recovery path tested against more than pod readiness. Keep the values file small, capture every render, validate identity and network boundaries, and treat each chart upgrade as a platform change with its own stop conditions.