Getting Started with ArgoCD

ArgoCD is a declarative, GitOps continuous delivery tool for Kubernetes. It automates the deployment of applications by continuously comparing the desired state defined in a Git repository with the actual live state in your Kubernetes cluster, and reconciling any differences — the core premise of GitOps.

Why ArgoCD?

Traditional CI/CD pipelines push changes to clusters using external tools and credentials. ArgoCD flips this model: it runs inside your cluster and pulls changes from Git. This approach provides:

• Git as Single Source of Truth: Every change is versioned, reviewed, and auditable in Git
• Easy Rollback: Revert a Git commit and ArgoCD automatically reverts the cluster state
• Cluster Disaster Recovery: Rebuild your entire cluster from the Git repository
• Better Access Control: Leverage Git's permission model (CODEOWNERS, branch protection) instead of granting CI systems direct cluster access

How ArgoCD Works — The Reconciliation Loop

At the heart of ArgoCD is a continuous reconciliation loop that detects and corrects configuration drift:

1. The Repo Server clones your Git repository and renders Helm/Kustomize/Jsonnet into raw Kubernetes manifests.
2. The Application Controller compares the desired state (from Git) with the live state (from the Kubernetes API).
3. If drift is detected and auto-sync is enabled, ArgoCD applies the changes automatically; otherwise it reports the app as Out of Sync .

Footnotes

1. Argo CD Official Documentation - Overview of ArgoCD, GitOps principles, and benefits of Git as single source of truth. ↩ ↩² ↩³ ↩⁴

2. Argo CD Component Architecture - Official component architecture documentation detailing dependencies and reconciliation flow. ↩

ArgoCD Architecture: Core Components

An ArgoCD installation consists of several components working together inside the argocd namespace 2:

Custom Resource Definitions (CRDs)

ArgoCD extends the Kubernetes API with three key CRDs:

• Application: Defines a deployed application — its source repo, destination cluster/namespace, and sync policy.
• AppProject: Groups applications with shared RBAC policies, source repos, and destination clusters.
• ApplicationSet: Automates the creation of multiple Application resources from generator patterns (cluster, git, list, matrix, etc.) .

Component Dependency Diagram

Footnotes

1. ArgoCD Architecture & Installation - AI Agent Factory - Comprehensive breakdown of five core components and installation steps. ↩ ↩² ↩³ ↩⁴

2. ArgoCD Architecture Core Components - KodeKloud - Component table and architecture details for CAPA certification prep. ↩ ↩²

3. Argo CD Getting Started - Official getting started guide with installation, CLI, access, and first application deployment. ↩

Alternative Installation: Helm Chart

For production deployments, the Helm chart offers more flexibility and configuration options :

1# Add the ArgoCD Helm repository
2helm repo add argo https://argoproj.github.io/argo-helm
3helm repo update
4
5# Install with default values
6helm install argocd argo/argo-cd -n argocd --create-namespace
7
8# Or with custom values for production
9helm install argocd argo/argo-cd -n argocd \
10  -f argocd-custom-values.yaml

A typical argocd-custom-values.yaml for production might include:

1server:
2  replicas: 2
3  ingress:
4    enabled: true
5    annotations:
6      cert-manager.io/cluster-issuer: letsencrypt-prod
7
8controller:
9  replicas: 1
10  resources:
11    requests:
12      cpu: 500m
13      memory: 512Mi
14
15redis:
16  ha:
17    enabled: true  # Enable Redis HA for production

Footnotes

1. GitOps with Argo CD: Comprehensive Installation Guide - Medium - Detailed guide covering default, custom path, and namespace-scoped RBAC installations. ↩

Understanding Sync Policies

The sync policy controls how and when ArgoCD synchronizes your application state :

Key Sync Options :

• CreateNamespace=true — Auto-create the destination namespace
• PrunePropagationPolicy=foreground — Control how pruned resources are deleted
• PruneLast=true — Prune resources after new ones are healthy
• ApplyOutOfSyncOnly=true — During auto-sync, only apply resources that differ (saves API server load)
• Validate=false — Skip server-side validation

Retry Configuration

Failed syncs can be automatically retried:

1syncPolicy:
2  automated:
3    prune: true
4    selfHeal: true
5  retry:
6    limit: 5
7    backoff:
8      duration: 5s    # Initial wait
9      factor: 2        # Exponential multiplier
10      maxDuration: 3m  # Maximum wait between retries

This implements exponential backoff: $5\text{s}, 10\text{s}, 20\text{s}, 40\text{s}, 80\text{s} \rightarrow 3\text{m}$ cap .

Footnotes

1. ArgoCD Sync Policies: A Practical Guide - Octopus Deploy - In-depth guide to manual, automated, self-heal, selective sync, and resource protection options. ↩ ↩² ↩³

Best Practices Summary

Drawing from community experience and official guidance 3:

1. Use Declarative Application Manifests — Store Application CRDs in Git, not just create them via CLI. This makes your ArgoCD configuration itself GitOps-managed.
2. Adopt the App of Apps or ApplicationSet Pattern — Manage fleet deployments declaratively rather than creating individual applications manually.
3. Pin ArgoCD Versions — Avoid using the stable tag in production; pin to a specific version to prevent unexpected upgrades .
4. Separate App Repos from Source Code — ArgoCD should point to a configuration repository (manifests, Helm values), not your source code repo. CI pipelines build images and update the config repo; ArgoCD deploys from the config repo .
5. Enable RBAC via AppProjects — Use AppProject CRDs to restrict which repos, clusters, and namespaces teams can deploy to.
6. Protect Critical Resources — Use the annotation argocd.argoproj.io/sync-options: Delete=false to prevent accidental deletion of resources like PersistentVolumeClaims .
7. Monitor ArgoCD Metrics — Expose Prometheus metrics and set up alerts for failed syncs, out-of-sync apps, and controller health.

Footnotes

1. Best Practices ArgoCD: K8s Deployment Strategy - Medium - Community best practices covering App of Apps, ApplicationSet, sync policies, and retry configuration. ↩

2. Argo CD Best Practices - Octopus Deploy - Production best practices including separation of source code and config repos, and audit trail maintenance. ↩ ↩²

3. Best practices for syncPolicy for CI/CD - GitHub Discussion - Community discussion on automated vs. manual sync tradeoffs in CI/CD pipelines. ↩

4. Argo CD Getting Started - Official getting started guide with installation, CLI, access, and first application deployment. ↩

5. ArgoCD Sync Policies: A Practical Guide - Octopus Deploy - In-depth guide to manual, automated, self-heal, selective sync, and resource protection options. ↩