ArgoCD / Flux GitOps Debug Prompt

You are a senior platform engineer who has run GitOps at scale with both ArgoCD and Flux. You can diagnose sync failures, drift, secret management, and multi-cluster patterns.

I will provide:
- The GitOps tool (ArgoCD / Flux)
- The symptom (sync failed, OutOfSync, app-of-apps not picking up, drift)
- App / GitRepository spec
- Recent logs

Your job:

1. **ArgoCD model**:
   - **Application** — declares git source + destination cluster + namespace
   - **AppProject** — groups apps, scope restrictions
   - **App-of-Apps** — Application that manages other Applications
   - **ApplicationSet** — templated app generation
2. **Flux model**:
   - **GitRepository** — defines git source
   - **Kustomization** — applies kustomize from a GitRepository path
   - **HelmRelease** — applies Helm chart
   - **OCIRepository, Bucket** — alternative sources
3. **For sync failures**:
   - Manifest errors (yaml parse, schema)
   - Missing CRDs (chicken-and-egg if CRD provided by same app)
   - Authentication to git
   - Webhook timeout
4. **For "OutOfSync" persistent**:
   - Difference between Git state and cluster state
   - Auto-sync disabled
   - Mutating webhook changing resources post-apply
5. **For drift**:
   - Manual changes via kubectl
   - ArgoCD: configure `prune: true` to remove non-Git resources
   - Flux: similar
6. **For app-of-apps**:
   - Root Application manages children
   - Sync waves to order
   - Common: namespaces created first, then workloads
7. **For ApplicationSet** (ArgoCD):
   - Generator: list, cluster, git, matrix
   - Templates per generated app
   - Pull request generator for review apps
8. **For secret management**:
   - SealedSecrets, ESO, Vault Operator
   - Don't commit plain secrets

Mark DESTRUCTIVE: `prune: true` on app where cluster has resources not in git (deletes them), force sync ignoring conflicts, removing apps managed by app-of-apps (orphans).

---

Tool: [ArgoCD / Flux]
Symptom: [DESCRIBE]
App / Kustomization spec:
```yaml
[PASTE]
```
Logs:
```
[PASTE]
```

Why this prompt works

GitOps tools have model-specific debugging. This prompt walks both.

How to use it

1. Identify tool (ArgoCD vs Flux).
2. For sync failures, check events.
3. For drift, audit recent manual changes.
4. For multi-cluster, verify destination config.

Useful commands

# ArgoCD
kubectl get applications -n argocd
kubectl get application <name> -n argocd -o yaml
argocd app list
argocd app sync <name>
argocd app diff <name>
argocd app get <name> --refresh
kubectl logs -n argocd deploy/argocd-application-controller -f

# Flux
kubectl get gitrepositories -A
kubectl get kustomizations -A
kubectl get helmreleases -A
flux get sources git
flux get kustomizations
flux logs --follow
flux reconcile kustomization <name>

Patterns

ArgoCD App

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: web
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://gitlab.example.com/team/manifests.git
    targetRevision: main
    path: apps/web/overlays/production
  destination:
    server: https://kubernetes.default.svc
    namespace: web
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
    - CreateNamespace=true
    - PrunePropagationPolicy=foreground
    retry:
      limit: 5
      backoff:
        duration: 5s
        factor: 2
        maxDuration: 3m

App-of-Apps

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: root
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://gitlab.example.com/team/manifests.git
    targetRevision: main
    path: apps                           # contains many Application YAMLs
  destination:
    server: https://kubernetes.default.svc
    namespace: argocd
  syncPolicy:
    automated:
      prune: true
      selfHeal: true

Flux Kustomization

apiVersion: source.toolkit.fluxcd.io/v1
kind: GitRepository
metadata:
  name: manifests
  namespace: flux-system
spec:
  interval: 1m
  url: https://gitlab.example.com/team/manifests.git
  ref:
    branch: main
---
apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
  name: web
  namespace: flux-system
spec:
  interval: 5m
  path: ./apps/web/overlays/production
  prune: true
  sourceRef:
    kind: GitRepository
    name: manifests
  targetNamespace: web
  timeout: 5m

ApplicationSet for review apps

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: review-apps
  namespace: argocd
spec:
  generators:
  - pullRequest:
      gitlab:
        project: "team/web"
        labels: ["preview"]
        tokenRef:
          secretName: gitlab-token
          key: token
  template:
    metadata:
      name: 'web-pr-{{number}}'
    spec:
      project: default
      source:
        repoURL: https://gitlab.example.com/team/web.git
        targetRevision: '{{head_sha}}'
        path: deploy/preview
      destination:
        server: https://kubernetes.default.svc
        namespace: 'preview-{{number}}'
      syncPolicy:
        automated:
          prune: true
          selfHeal: true

Common findings this catches

• Sync failed: CRD not found → install CRD app first (sync wave -1).
• OutOfSync forever → mutating webhook drift; tune ignoreDifferences.
• Pruned resources unintentionally → repo missing them; add or scope.
• App-of-apps not picking up new → check root app sync.
• ApplicationSet generating too many → restrict generator.
• Git authentication fails → token expired.
• Helm chart values mismatch → values not in Git as expected.

When to escalate

• Production sync issues during incident — engage platform team.
• ApplicationSet template debugging — share with team.
• Migration between tools (ArgoCD ↔ Flux) — major project.