The No-Nonsense Guide to ArgoCD

For a broader view of GitOps tools, see our 2025 comparison.

ArgoCD is the GitOps tool most Kubernetes teams reach for, but the official documentation only tells you how to drive it on a freshly paved road. Out in the real world, where the pavement ends, you'll find potholes, weird engine noises, and a whole lot of community forum posts from people stuck in the mud.

This is a field guide based on what people complain about on Reddit, GitHub issues, and Stack Overflow. It covers the problems that don't make it into the marketing material.

The Sync & Performance Nightmare

The most common sign something’s wrong in ArgoCD land is the dreaded sync timeout or an application controller pegging the CPU. I've seen teams immediately throw more memory and CPU at the problem, and it rarely works.

The cause is almost never raw resources. It’s usually one of these:

• Inefficient Manifest Generation: Your argocd-repo-server is choking because your Helm chart is a monster or your Kustomize setup is too complex.
• API Server Throttling: The argocd-application-controller is hammering the Kubernetes API server too hard, causing it to throttle requests.
• Bad Caching: You're not using caching effectively, forcing ArgoCD to re-calculate everything on every reconciliation loop.

Before you scale up, tune the controller. These are the knobs to look at first.

Start here. Tweak these values, watch your metrics, and only then consider giving it more raw power.

Helm Hooks Are a Trap

What trips up more teams than anything else is that ArgoCD doesn't run helm install or helm upgrade. It runs helm template.

So ArgoCD has no concept of an "install" vs. an "upgrade." It's just a "sync." The nasty side effect is that your Helm pre-install and pre-upgrade hooks both run on every sync. If your hooks aren't idempotent, meaning they can run over and over without causing problems, you're in for a world of pain.

The fix is to design your hooks to be harmless on repeated runs. For a one-off job, that means telling ArgoCD to clean up the hook resource after it succeeds.

# In your hook's manifest (e.g., a Job)
apiVersion: batch/v1
kind: Job
metadata:
  name: my-presync-db-migration
  annotations:
    # This is the ArgoCD hook annotation
    argocd.argoproj.io/hook: PreSync
    # This tells ArgoCD to delete the Job object once the hook succeeds
    argocd.argoproj.io/hook-delete-policy: HookSucceeded
spec:
  template:
    spec:
      containers:
      - name: db-migrator
        image: my-company/db-migrator:1.2.0
        # ... rest of your job spec
      restartPolicy: Never
  backoffLimit: 1

Helm's lookup function is out too. Since helm template runs without cluster access, lookup won't work. You'll have to refactor your charts to pass that data in via values.

The App-of-Apps Spaghetti

The "App-of-Apps" pattern is the standard way to manage complex environments. You have a root app that deploys... other apps. It's a great idea until you have dependencies. What if your monitoring app needs the CRDs from your Prometheus operator app to be deployed first?

By default, ArgoCD syncs them all at once, so nothing guarantees the CRDs exist by the time the monitoring app needs them.

The solution is Sync Waves. It’s an annotation that puts the apps in order. Resources in lower-numbered waves are synced and must become healthy before ArgoCD moves on to the next wave.

# In your Prometheus Operator Application manifest
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: prometheus-operator
  annotations:
    # Wave 0: Deploy the operator CRDs first
    argocd.argoproj.io/sync-wave: "0"
# ...
 
---
 
# In your Monitoring Application manifest
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: kube-prometheus-stack
  annotations:
    # Wave 1: Deploy after the operator is ready
    argocd.argoproj.io/sync-wave: "1"
# ...

Without sync waves, App-of-Apps stops working once your apps depend on each other.

The Terraform-to-ArgoCD Chasm

This is the seam where CI/CD pipelines for Terraform and OpenTofu meet GitOps, and it gets awkward. Before you get here, it helps to settle where Terraform should stop and ArgoCD should take over, which is its own decision we work through in Terraform vs GitOps for Kubernetes. Say you provision an AWS RDS database with Terraform. The Terraform outputs, the database endpoint, username, and a secret ARN, now need to flow into the Kubernetes application that ArgoCD is deploying. How?

This is a classic handoff problem, and the community has come up with some clever, if clunky, workarounds:

1. Parameter Store: Your CI pipeline runs Terraform, which writes the outputs to AWS Parameter Store. Then, your ArgoCD application uses the External Secrets Operator to read from Parameter Store and create a Kubernetes secret.
2. Commit-Back-to-Git: Terraform uses a GitHub provider to commit a values.yaml file containing the outputs directly back into your GitOps repo.

Both of these work, but they feel like duct tape. Either an external store sits in the middle of your process, or your infrastructure tool pollutes your application configuration history.

This is where a more integrated platform makes a lot more sense. In Scalr, for instance, a workspace's outputs can be read by other workspaces through the scalr_outputs data source or remote state sharing, and run triggers start a downstream workspace after an upstream apply. Scalr doesn't deploy the application or drive ArgoCD itself, so you still need a handoff into the cluster, but the outputs come from one governed place. You solve the problem at the architectural level instead of patching over it with clever scripts.

Secrets: Just Stop Using the Vault Plugin

For years, people used the ArgoCD Vault Plugin (AVP) to inject secrets during manifest generation. If you're still doing this, stop. The ArgoCD maintainers themselves now officially recommend against it.

It's a security anti-pattern. Using AVP means your argocd-repo-server needs a credential to your Vault instance. This widens your attack surface. Worse, the rendered manifests, now with plaintext secrets, get stored in ArgoCD's Redis cache.

The modern, secure way is to use an operator-based pattern.

• The Operator: You install something like the External Secrets Operator (ESO) in your cluster.
• The Process: You commit an ExternalSecret manifest to Git. This manifest tells ESO where to find the secret in Vault (or AWS/GCP/Azure secret managers). ESO then fetches the secret and creates a native Kubernetes Secret object inside the cluster.
• ArgoCD's Role: Your application, managed by ArgoCD, mounts the native Kubernetes Secret like it always would.

In this model, ArgoCD is completely ignorant of Vault. It doesn't need credentials, and it doesn't handle plaintext secrets. It just manages the ExternalSecret custom resource, and the operator handles the sensitive work. That's a much cleaner separation of concerns.

Where ArgoCD trips teams up

Most ArgoCD pain comes from a handful of failure modes the docs gloss over. Tune the controller parameters before scaling resources. Design hooks that survive repeated runs, since helm template reruns them on every sync. Use Sync Waves to order dependent apps, and hand secrets to an operator like External Secrets rather than the Vault Plugin. The happy path in the docs won't surface any of these. The community forum threads will.

Key Sources Used:

• Argo CD Official Documentation (argo-cd.readthedocs.io)
• r/ArgoCD & r/kubernetes on Reddit for community-reported issues
• Akuity Blog: How to Integrate Terraform with Argo CD for GitOps Workflows
• Akuity Blog: The 3 Most Common Argo CD Architectures Explained
• Argo CD GitHub Discussions and Issues