# Managing K8S Flux Deep

> Use when working with K8S Flux Deep — flux CD deep-dive management for Kubernetes GitOps delivery. Covers GitRepository sources, Kustomization reconciliation, HelmRelease status, HelmRepository health, ImagePolicy automation, notification providers, and multi-tenancy configurations. Use when debugging reconciliation failures, analyzing Flux source health, reviewing Helm release drift, or auditing image automation pipelines.

- Skill: `cloudthinker-ai/managing-k8s-flux-deep` (Agent Skill)
- Install (CLI): `npx skillmds@latest add cloudthinker-ai/managing-k8s-flux-deep`
- Raw SKILL.md: https://api.skillmd.com/api/skills/cloudthinker-ai/managing-k8s-flux-deep/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: cloudthinker-ai (https://skillmd.com/u/cloudthinker-ai)
- Updated: 2026-09-08
- Page: https://skillmd.com/skills/cloudthinker-ai/managing-k8s-flux-deep

---


# Flux CD Deep-Dive Skill

Advanced analysis of Flux CD GitOps sources, reconciliation, and deployment pipelines.

## MANDATORY: Discovery-First Pattern

**Always check Flux installation and source health before inspecting reconciliation.**

### Phase 1: Discovery

```bash
#!/bin/bash

echo "=== Flux Components ==="
kubectl get deployment -n flux-system -o custom-columns='NAME:.metadata.name,READY:.status.readyReplicas,IMAGE:.spec.template.spec.containers[0].image' 2>/dev/null

echo ""
echo "=== Flux Version ==="
kubectl get deployment source-controller -n flux-system -o jsonpath='{.spec.template.spec.containers[0].image}' 2>/dev/null
echo ""

echo ""
echo "=== GitRepositories ==="
kubectl get gitrepositories --all-namespaces -o custom-columns='NAMESPACE:.metadata.namespace,NAME:.metadata.name,READY:.status.conditions[?(@.type=="Ready")].status,REVISION:.status.artifact.revision,AGE:.metadata.creationTimestamp' 2>/dev/null | head -15

echo ""
echo "=== HelmRepositories ==="
kubectl get helmrepositories --all-namespaces -o custom-columns='NAMESPACE:.metadata.namespace,NAME:.metadata.name,READY:.status.conditions[?(@.type=="Ready")].status,URL:.spec.url' 2>/dev/null | head -15

echo ""
echo "=== OCIRepositories ==="
kubectl get ocirepositories --all-namespaces -o custom-columns='NAMESPACE:.metadata.namespace,NAME:.metadata.name,READY:.status.conditions[?(@.type=="Ready")].status' 2>/dev/null | head -10

echo ""
echo "=== Kustomizations ==="
kubectl get kustomizations --all-namespaces -o custom-columns='NAMESPACE:.metadata.namespace,NAME:.metadata.name,READY:.status.conditions[?(@.type=="Ready")].status,REVISION:.status.lastAppliedRevision' 2>/dev/null | head -15
```

### Phase 2: Analysis

```bash
#!/bin/bash

echo "=== HelmReleases ==="
kubectl get helmreleases --all-namespaces -o custom-columns='NAMESPACE:.metadata.namespace,NAME:.metadata.name,READY:.status.conditions[?(@.type=="Ready")].status,CHART:.spec.chart.spec.chart,VERSION:.spec.chart.spec.version' 2>/dev/null | head -15

echo ""
echo "=== Failed Reconciliations ==="
kubectl get kustomizations,helmreleases --all-namespaces -o json 2>/dev/null | jq -r '
  .items[] |
  select(.status.conditions[]? | select(.type == "Ready" and .status != "True")) |
  "\(.kind)/\(.metadata.name)\t\(.status.conditions[] | select(.type == "Ready") | .reason): \(.message // "")[0:80]"
' | head -15

echo ""
echo "=== Source Errors ==="
kubectl get gitrepositories,helmrepositories --all-namespaces -o json 2>/dev/null | jq -r '
  .items[] |
  select(.status.conditions[]? | select(.type == "Ready" and .status != "True")) |
  "\(.kind)/\(.metadata.name)\t\(.status.conditions[] | select(.type == "Ready") | .message // "unknown")[0:80]"
' | head -10

echo ""
echo "=== Image Policies ==="
kubectl get imagepolicies --all-namespaces -o custom-columns='NAMESPACE:.metadata.namespace,NAME:.metadata.name,LATEST:.status.latestImage' 2>/dev/null | head -10

echo ""
echo "=== Image Update Automations ==="
kubectl get imageupdateautomations --all-namespaces -o custom-columns='NAMESPACE:.metadata.namespace,NAME:.metadata.name,LAST_RUN:.status.lastAutomationRunTime' 2>/dev/null | head -10

echo ""
echo "=== Notification Providers ==="
kubectl get providers --all-namespaces -o custom-columns='NAMESPACE:.metadata.namespace,NAME:.metadata.name,TYPE:.spec.type' 2>/dev/null | head -10

echo ""
echo "=== Alerts ==="
kubectl get alerts --all-namespaces -o custom-columns='NAMESPACE:.metadata.namespace,NAME:.metadata.name,SEVERITY:.spec.summary' 2>/dev/null | head -10

echo ""
echo "=== Suspended Resources ==="
kubectl get kustomizations,helmreleases --all-namespaces -o json 2>/dev/null | jq -r '
  .items[] | select(.spec.suspend == true) |
  "\(.kind)/\(.metadata.namespace)/\(.metadata.name)\tSUSPENDED"
'

echo ""
echo "=== Source Controller Logs (errors) ==="
kubectl logs deployment/source-controller -n flux-system --tail=15 2>/dev/null | grep -i "error\|fail" | head -5
```

## Output Format

- Target ≤50 lines per output
- Use `-o custom-columns` for CRD resource listings
- Show Ready status and last applied revision for quick health check
- Group HelmReleases by namespace for organized view
- Never dump full Kustomization patches -- show source ref and status only

## Anti-Hallucination Rules

1. **NEVER assume resource names** — always discover via CLI/API in Phase 1 before referencing in Phase 2.
2. **NEVER fabricate metric names or dimensions** — verify against the service documentation or `--help` output.
3. **NEVER mix CLI commands between service versions** — confirm which version/API you are targeting.
4. **ALWAYS use the discovery → verify → analyze chain** — every resource referenced must have been discovered first.
5. **ALWAYS handle empty results gracefully** — an empty response is valid data, not an error to retry.

## Counter-Rationalizations

| Shortcut | Counter | Why |
|----------|---------|-----|
| "I'll skip discovery and check known resources" | Always run Phase 1 discovery first | Resource names change, new resources appear — assumed names cause errors |
| "The user only asked for a quick check" | Follow the full discovery → analysis flow | Quick checks miss critical issues; structured analysis catches silent failures |
| "Default configuration is probably fine" | Audit configuration explicitly | Defaults often leave logging, security, and optimization features disabled |
| "Metrics aren't needed for this" | Always check relevant metrics when available | API/CLI responses show current state; metrics reveal trends and intermittent issues |
| "I don't have access to that" | Try the command and report the actual error | Assumed permission failures prevent useful investigation; actual errors are informative |

## Common Pitfalls

- **Dependency ordering**: Kustomizations support `dependsOn` -- circular dependencies cause deadlocks
- **Suspend flag**: `spec.suspend: true` stops reconciliation -- check before assuming failures
- **Source interval**: `spec.interval` controls how often sources are checked -- too frequent causes rate limits
- **HelmRelease remediation**: `spec.install.remediation` and `spec.upgrade.remediation` control retry behavior
- **Drift detection**: Enable `spec.force` on Kustomizations to correct drift -- but may cause disruption
- **Multi-tenancy**: Use `spec.serviceAccountName` on Kustomizations for RBAC scoping per tenant
- **Image automation**: Requires image-reflector and image-automation controllers -- not installed by default
- **Prune**: `spec.prune: true` on Kustomizations deletes resources removed from Git -- use with caution
- **Health checks**: Custom health checks in Kustomizations can delay Ready status -- check `spec.healthChecks`