/gitops

name: gitops
description: "Flux CD and Argo CD — two modes. debug: five structured debug workflows for live clusters (installation, source, HelmRelease, Kustomization, ResourceSet) producing a five-section report. audit: six-phase read-only repo analysis (discovery, validation, API compliance, best practices, security) producing a prioritised Critical/Warning/Info report."
argument-hint: "debug [describe symptom or paste flux/argocd output] | audit [repo path or paste directory listing]"
title: "GitOps Command"
sidebar_label: "gitops"
custom_edit_url: null

---

Interactive Wizard (fires when $ARGUMENTS is empty)

When invoked with no arguments, ask before proceeding:

**Q1 — Mode?**

Are you debugging a live cluster issue or auditing a GitOps repository?
  1. debug — live cluster troubleshooting (Flux/Argo error, not reconciling, pod failure)
  2. audit — read-only repository health check (before merge, before release, onboarding)

Enter 1 or 2:

**Q2 — Context** (after mode selected, one at a time):

• **debug**: `Describe the symptom or paste the flux get / kubectl output (error message, resource name, namespace):`
• **audit**: `Provide the repo path or paste the directory listing (or run: bash $SCRIPTS/discover.sh -d . if tooling is set up):`

Then proceed with the relevant mode below.

---

You are a senior platform engineer specialising in GitOps with Flux CD and Argo CD.

The input is: $ARGUMENTS

---

Step 1 — Identify the mode

| If the input starts with or describes… | Use | |---|---| | `debug`, an error message, `flux get` output, pod logs, "not reconciling" | **Debug mode** → work through the debug workflows below | | `audit`, a repo path, "before merge", "is this correct", directory listing | **Audit mode** → work through the 6-phase audit below |

If the mode is ambiguous, ask: > "Are you debugging a live cluster issue or auditing a GitOps repository?"

---

Debug mode — live cluster troubleshooting

1. Identify the tool and layer

**Flux CD layers:**

• **Source** — GitRepository, OCIRepository, HelmRepository, Bucket
• **Artifact** — Kustomization build, HelmChart render
• **Reconciliation** — Kustomization apply, HelmRelease install/upgrade
• **Runtime** — pod health, hook failures, dependency ordering
• **Operator** — FluxInstance, ResourceSet, ResourceSetInputProvider

**Argo CD layers:**

• **Source** — repo connection, credentials, branch/path
• **Diff** — ignoreDifferences, server-side apply drift
• **Sync** — sync waves, resource hooks, namespace creation
• **Health** — custom health checks, resource status

---

2. Flux debug workflows

Work through the relevant workflow. Follow the dependency chain top-down — do not skip layers.

Workflow 1 — Installation check

Verify controllers are healthy before debugging individual resources.

flux get all -A
kubectl get fluxinstance flux -n flux-system -o yaml
kubectl get fluxreport flux -n flux-system -o yaml
kubectl get pods -n flux-system
kubectl logs -n flux-system deploy/source-controller | tail -50
kubectl logs -n flux-system deploy/kustomize-controller | tail -50
kubectl logs -n flux-system deploy/helm-controller | tail -50

**Controller failure modes:**

| Symptom | Cause | Fix | |---|---|---| | Controller pod not running | Resource pressure, image pull failure, missing CRDs | Check `kubectl describe pod`, node conditions, image pull secrets | | Controller `OOMKilled` / crashlooping | Insufficient memory limits | Increase limits via `FluxInstance spec.kustomize.patches` or delete pod to reset | | `spec.suspend: true` on FluxInstance | Intentional pause | Do not flag as error — resume with `kubectl patch fluxinstance flux --type=merge -p '{"spec":{"suspend":false}}'` | | `Ready: Unknown` / Progressing | Reconciliation in flight | Wait; check `lastTransitionTime` relative to `interval` | | Missing CRDs after upgrade | Flux component not upgraded | Re-run bootstrap or update `FluxInstance.spec.distribution.version` |

Workflow 1b — Source failures

Check sources separately when controllers are healthy but resources are not reconciling.

flux get sources all -A
kubectl describe gitrepository <name> -n flux-system
kubectl describe ocirepository <name> -n flux-system

**Source failure modes:**

| Source | Symptom | Cause | Fix | |---|---|---|---| | `GitRepository` | `FetchFailed` | Wrong credentials, expired token, wrong SSH key | Check `secretRef`; verify `identity`/`known_hosts` keys; SSH scp-style URLs (`git@host:repo`) are NOT supported — use `ssh://git@host/repo` | | `OCIRepository` | `FetchFailed` | Cloud registry auth misconfigured | Check `spec.provider` for ECR/GCR/ACR; verify workload identity annotation on controller SA | | `OCIRepository` | Cosign verify failure | Signature missing or OIDC issuer/subject mismatch | Check `spec.verify.matchOIDCIdentity`; verify signature was pushed by CI | | `HelmChart` | Not ready | Referenced `HelmRepository` not ready | Fix the source first — HelmChart inherits source failures | | `HelmRepository` (OCI type) | No status conditions | OCI HelmRepositories show no status | Migrate to `OCIRepository` with `spec.chartRef` |

Workflow 2 — HelmRelease trace

Trace: HelmRelease spec/status → managing object → `valuesFrom` references → chart source → managed inventory → pod logs.

# Step 1: Check HelmRelease status
flux get helmrelease <name> -n <namespace>
kubectl describe helmrelease <name> -n <namespace>
flux logs --kind=HelmRelease --name=<name> --namespace=<namespace>

# Step 2: Trace the managing object via labels — don't guess, read the labels
kubectl get helmrelease <name> -n <namespace> \
  -o jsonpath='{.metadata.labels}' | jq
# Look for:
#   kustomize.toolkit.fluxcd.io/name  → parent Kustomization
#   resourceset.fluxcd.io/name        → parent ResourceSet

# Step 3: Check valuesFrom ConfigMaps / Secrets
kubectl get configmap,secret -n <namespace>

# Step 4: Check chart source
flux get sources oci -