argocd
Configure Argo CD Applications, AppProjects, and sync policies; inspect health checks and troubleshoot GitOps rollouts.
SKILL.mdskills/argocd/SKILL.md
GitHubArgo CD GitOps AI Skill Guide (Claude)
Overview & Engine Architecture
Argo CD continuously reconciles cluster state to Git-defined desired state (plain YAML, Helm, Kustomize, Jsonnet). An Application binds repo path + revision to a cluster/namespace; AppProject enforces allowlists. The controller diff-computes live vs desired, sync applies patches, and health assesses resource readiness. Agents treat Git as source of truth—no kubectl edit on managed objects—and respect prune/selfHeal blast radius.
┌─────────────────────────────────────────────────────────────┐
│ Argo CD reconciliation │
│ │
│ Git repo (main) → Application controller │
│ ↓ compare + hydrate (helm/kustomize) │
│ Cluster API ← sync (hooks, waves, replace options) │
│ UI/CLI: Synced/OutOfSync, Healthy/Degraded/Progressing │
└─────────────────────────────────────────────────────────────┘
When to use / when not to
Use when
- Wiring CD so merged Git revisions deploy to Kubernetes automatically.
- Debugging
OutOfSync,Degraded, sync hooks, or HPA/replica drift. - Designing AppProject boundaries for multi-team/multi-cluster fleets.
Do not use when
- Building container images—CI updates tags/digests in Git (
@docker,@github-actions). - Cluster creation—
@terraform; raw pod debug—@kubernetes.
Operational Capabilities & Agent Directives
- Desired state lives in Git; manual cluster edits are debt—revert or commit fix.
- Automated sync: enable
prune+selfHealonly after nonprod dry-runs; understand prune deletes resources removed from Git. ignoreDifferencesalone does not skip fields at sync time—addsyncOptions: [RespectIgnoreDifferences=true]so ignored fields (e.g./spec/replicasunder HPA) are not overwritten during apply.- AppProject scopes: allowed repos, destinations, resource kinds; deny cluster-scoped surprises.
- Sync waves / hooks: document ordering; failed PreSync hooks block release—check hook pod logs.
- Multi-source Applications: document which source owns which path; avoid opaque overrides.
- Never embed cluster admin tokens in Application manifests; use in-cluster
https://kubernetes.default.svcor registered clusters with RBAC. - Image updates: CI opens PR bumping image digest in values/overlays—Argo watches Git, not CI kubectl.
Production Example: Application + project constraints
apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
name: platform
namespace: argocd
spec:
sourceRepos:
- https://github.com/example/platform-gitops
destinations:
- namespace: apps-*
server: https://kubernetes.default.svc
clusterResourceWhitelist:
- group: ""
kind: Namespace
---
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
name: api
namespace: argocd
spec:
project: platform
source:
repoURL: https://github.com/example/platform-gitops
targetRevision: main
path: apps/api/overlays/prod
helm:
valueFiles: [values.yaml]
destination:
server: https://kubernetes.default.svc
namespace: api
ignoreDifferences:
- group: apps
kind: Deployment
jsonPointers: [/spec/replicas]
syncPolicy:
automated:
prune: true
selfHeal: true
syncOptions:
- CreateNamespace=true
- RespectIgnoreDifferences=true
CLI diagnostics:
argocd app get api
argocd app diff api
argocd app sync api --dry-run
argocd app history api
argocd app rollback api <id>
Technical Troubleshooting Matrix
| Status | Meaning | Next step |
|---|---|---|
| OutOfSync | Git ≠ live | app diff; commit fix or sync if Git intended |
| Degraded | Unhealthy resource | Pod events/logs; fix manifest health checks |
| Progressing | Rollout in flight | Wait; check RS; surge limits |
| SyncFailed hook | PreSync/PostSync job failed | Logs for hook Job |
| Repeated replica fights | HPA vs Git replicas | ignoreDifferences + RespectIgnoreDifferences |
| Prune deleted prod NS | prune+removed manifest | Restore from Git; use Prune=confirm for critical kinds |
| Mass pod restart after sync | Probe storm / resource surge | Stagger apps; @kubernetes probe tuning |
Best Practices
- One Application per deployable service; ApplicationSet for fleet generators.
- Protect
mainwith PR checks; Argo tracks reviewed SHAs only. - Separate envs by overlay path or branch strategy—document promotion.
- Use
argocd.argoproj.io/compare-options/ignore-differencesannotation for resource-level rules when App spec locked down. - Observability: alert on sync failure and
Degradedduration; link@grafanapanels.
Limitations
- Argo CD does not scan images—pair with
@trivyin CI before tag bumps land in Git. - Automated prune can delete quickly—test AppProjects and sync options in nonprod.
RespectIgnoreDifferencesapplies only after resource exists; first create uses full desired manifest.- Stop and ask if repo URL, cluster credential, or blast radius of prune is unclear.
Related Skills
@kubernetes— workload failure analysis@helm— chart rendering inside Application source@fluxcd— alternative GitOps engine comparison@github-actions— CI that commits image digest bumps@docker— image build and digest pinning
Agent Operational Directive
MANDATORY: Do not recommend kubectl edits for Argo-managed production objects—fix Git and sync. When using
ignoreDifferencesfor controller-owned fields, always addRespectIgnoreDifferences=true. Treat automated prune as destructive capability requiring nonprod validation. For fork/untrusted flows, keep deploy credentials out of PR workflows (@github-actions).