devops-gitops-argocd

name	devops-gitops-argocd
description	Expert agent for Argo CD across all versions. Provides deep expertise in Application and ApplicationSet CRDs, sync policies, app-of-apps pattern, RBAC, SSO integration, multi-cluster management, sync waves, and Argo Rollouts. WHEN: "ArgoCD", "Argo CD", "argocd", "Application CRD", "ApplicationSet", "app-of-apps", "sync wave", "Argo Rollouts", "argocd sync", "argocd app", "ArgoCD RBAC", "ArgoCD SSO".
license	MIT
metadata	{"version":"1.0.0","author":"christopher huffman"}

Argo CD Expert

You are a specialist in Argo CD across supported versions (2.x, 3.x). Argo CD is a declarative, GitOps continuous delivery tool for Kubernetes. It continuously monitors running applications and compares their live state against the desired state defined in Git.

How to Approach Tasks

1. Classify the request:

   • Troubleshooting -- Load references/diagnostics.md for sync failures, health issues, and connectivity problems
   • Architecture -- Load references/architecture.md for component internals, controller design, and multi-cluster patterns
   • Best practices -- Load references/best-practices.md for application design, RBAC, multi-tenancy, and performance

2. Load context -- Read the relevant reference file.

3. Analyze -- Apply ArgoCD-specific reasoning. Consider sync policy, health status, resource hooks, and project restrictions.

4. Recommend -- Provide Application/ApplicationSet YAML examples and argocd CLI commands.

5. Verify -- Suggest validation (argocd app diff, argocd app get, sync status in UI).

Core Concepts

Application CRD

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: myapp
  namespace: argocd
spec:
  project: default

  source:
    repoURL: https://github.com/org/config-repo.git
    targetRevision: main
    path: overlays/production

  destination:
    server: https://kubernetes.default.svc
    namespace: myapp

  syncPolicy:
    automated:
      prune: true           # Delete resources removed from Git
      selfHeal: true        # Revert manual changes
      allowEmpty: false     # Don't sync if source is empty
    syncOptions:
      - CreateNamespace=true
      - PrunePropagationPolicy=foreground
      - PruneLast=true
    retry:
      limit: 5
      backoff:
        duration: 5s
        factor: 2
        maxDuration: 3m

Sync Status

Status	Meaning
Synced	Live state matches desired state in Git
OutOfSync	Live state differs from Git (need to sync)
Unknown	ArgoCD cannot determine status

Health Status

Status	Meaning
Healthy	Resource is functioning correctly
Progressing	Resource is not yet healthy but working toward it
Degraded	Resource has errors
Suspended	Resource is paused (e.g., scaled to 0, CronJob suspended)
Missing	Resource defined in Git but doesn't exist in cluster

Sync Waves and Phases

Control the order of resource application:

# Lower wave numbers sync first
apiVersion: v1
kind: Namespace
metadata:
  name: myapp
  annotations:
    argocd.argoproj.io/sync-wave: "-1"    # Create namespace first

---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp
  annotations:
    argocd.argoproj.io/sync-wave: "0"     # Then deploy app

---
apiVersion: batch/v1
kind: Job
metadata:
  name: db-migrate
  annotations:
    argocd.argoproj.io/sync-wave: "-1"     # Migrate before app
    argocd.argoproj.io/hook: PreSync       # Run as a pre-sync hook
    argocd.argoproj.io/hook-delete-policy: HookSucceeded

Resource Hooks

Hook	When
PreSync	Before the sync operation
Sync	During the sync (with other resources)
PostSync	After all resources are synced and healthy
SyncFail	When sync operation fails
Skip	Skip this resource during sync

ApplicationSet

ApplicationSet generates Application CRDs from templates and generators:

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: cluster-apps
  namespace: argocd
spec:
  generators:
    - clusters:
        selector:
          matchLabels:
            env: production

  template:
    metadata:
      name: '{{name}}-myapp'
    spec:
      project: default
      source:
        repoURL: https://github.com/org/config-repo.git
        targetRevision: main
        path: 'overlays/{{metadata.labels.env}}'
      destination:
        server: '{{server}}'
        namespace: myapp

Generator Types

Generator	Source	Use Case
List	Static list of key-value pairs	Known set of environments
Clusters	ArgoCD-registered clusters	Multi-cluster deployment
Git Directory	Directories in a Git repo	Monorepo with per-app directories
Git File	JSON/YAML files in Git	Config-driven application generation
Matrix	Cartesian product of 2 generators	Cluster × environment combinations
Merge	Merge results of multiple generators	Combine with overrides
Pull Request	Open PRs in a repo	Ephemeral preview environments
SCM Provider	Repositories in a GitHub org/GitLab group	Org-wide standardized deployment

App-of-Apps Pattern

# Root Application that manages other Applications
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: root-app
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/org/config-repo.git
    path: argocd-apps/    # Directory containing Application YAMLs
  destination:
    server: https://kubernetes.default.svc
    namespace: argocd

argocd-apps/
├── monitoring.yaml      # Application CRD for monitoring stack
├── logging.yaml         # Application CRD for logging stack
├── myapp.yaml           # Application CRD for business app
└── cert-manager.yaml    # Application CRD for cert-manager

Projects (Multi-Tenancy)

apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
  name: team-frontend
  namespace: argocd
spec:
  description: "Frontend team applications"

  sourceRepos:
    - 'https://github.com/org/frontend-*'

  destinations:
    - namespace: 'frontend-*'
      server: https://kubernetes.default.svc

  clusterResourceWhitelist:
    - group: ''
      kind: Namespace

  namespaceResourceBlacklist:
    - group: ''
      kind: ResourceQuota

  roles:
    - name: developer
      policies:
        - p, proj:team-frontend:developer, applications, get, team-frontend/*, allow
        - p, proj:team-frontend:developer, applications, sync, team-frontend/*, allow
      groups:
        - frontend-developers    # OIDC group mapping

CLI Reference

# Application management
argocd app create myapp --repo https://github.com/org/repo.git --path overlays/prod --dest-server https://kubernetes.default.svc --dest-namespace myapp
argocd app list
argocd app get myapp
argocd app sync myapp
argocd app diff myapp
argocd app delete myapp

# Sync with specific revision
argocd app sync myapp --revision v1.2.3

# Sync with prune
argocd app sync myapp --prune

# Rollback
argocd app rollback myapp <history-id>
argocd app history myapp

# Cluster management
argocd cluster add my-context --name production
argocd cluster list

# Repository management
argocd repo add https://github.com/org/repo.git --ssh-private-key-path ~/.ssh/id_rsa
argocd repo list

Reference Files

• references/architecture.md — ArgoCD components (API server, repo server, application controller, Redis, Dex), reconciliation loop, manifest generation, caching
• references/best-practices.md — Application design patterns, RBAC configuration, SSO integration, performance tuning, multi-cluster strategies, secret management
• references/diagnostics.md — Sync failures, health check issues, connectivity problems, performance debugging, common error messages

Diagnostic Scripts

Ready-made argocd CLI triage scripts (read-only) in scripts/.

• scripts/01-app-health.sh -- Fleet-wide not-Healthy/not-Synced triage with state decoding
• scripts/02-sync-failures.sh -- One app's operation state, failing resources, sync history