gitops-cluster-debug

Diagnoses Kubernetes clusters and generates actionable remediation steps for Common | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | issues.

204|10|Updated Feb 21, 2026
One-click install
npx skills add https://github.com/fluxcd/agent-skills --skill gitops-cluster-debug
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: gitops-cluster-debug
Source: https://github.com/fluxcd/agent-skills/tree/main/skills/gitops-cluster-debug
Command: npx skills add https://github.com/fluxcd/agent-skills --skill gitops-cluster-debug

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) and assets (resource) components.

What problem does it solve?

Debug Flux on live Kubernetes clusters by diagnosing installation health, controller readiness, and resource status to surface root causes and guide remediation.

Core Features & Use Cases

  • Workflow-driven cluster debugging: perform Flux installation checks, inspect FluxInstance, FluxReport, and controller deployments; trace issues through Kustomizations, HelmReleases, ResourceSets, and Git repositories; read logs and inventory to build root-cause analyses.
  • Guided remediation: generate actionable steps, commands, and references to fix issues on a live cluster.
  • Real-world scenarios: reproduce troubleshooting patterns for common Flux failures like fetch errors, RBAC, or degraded controllers.

Quick Start

Connect to the target cluster and run the live-cluster debugging workflow to identify Flux issues and generate a remediation plan.

Frequently Asked Questions about gitops-cluster-debug

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I debug Flux on a live Kubernetes cluster when resources are not syncing?

To debug Flux on a live Kubernetes cluster, run a structured debugging workflow to verify FluxInstance readiness, inspect controller deployments, and trace dependencies from Git repositories to managed resources. This identifies root causes like fetch errors or RBAC issues and generates remediation steps.

What is the best way to find the root cause of degraded Flux controllers in my cluster?

The best way to find the root cause of degraded Flux controllers is to inspect FluxReports and controller deployments, read logs, and trace issues through Kustomizations and HelmReleases. This workflow surfaces authentication or resource-readiness problems and provides concrete commands to resolve them.

Why does my Flux HelmRelease fail to fetch from the source Git repository?

Flux HelmRelease fetch failures often stem from authentication problems or unresolved source dependencies. A structured debugging workflow checks FluxInstance readiness, traces dependencies from sources to managed resources, and surfaces these specific root causes to guide your remediation.

Can I use this workflow to troubleshoot RBAC issues affecting Flux resources?

Yes, you can troubleshoot Flux RBAC issues by applying the live-cluster debugging workflow. It verifies Flux installation health, inspects FluxReports, and explicitly surfaces authentication and RBAC problems, providing concrete commands and references to fix the target cluster.

How do I diagnose Flux installation health and check FluxInstance readiness?

Diagnose Flux installation health by performing workflow-driven checks on FluxInstance readiness and controller deployments. The process inspects live-cluster status, reads logs, and builds a root-cause analysis to identify unresolved issues and generate actionable remediation steps.

What are common Flux failures I can reproduce troubleshooting patterns for?

Common Flux failures you can reproduce troubleshooting patterns for include fetch errors, RBAC misconfigurations, and degraded controllers. The debugging workflow traces dependencies across Kustomizations, HelmReleases, and ResourceSets to identify these issues and guide remediation.