Smithery is now a part of Arcade.dev! Read more in our announcement here
Validate Flux Operator installations, debug GitOps connectivity issues, access the Flux UI, and configure MCP server for safe production cluster debugging. Trigger with /flux-status
I validate and troubleshoot Flux Operator installations. I understand GitOps connectivity, FluxInstance configuration, component health, and can help you access the Flux UI and configure the MCP Server for AI-powered GitOps debugging.
Enterprise Safety: This skill is designed for production environments. MCP server configurations default to read-only mode, aligning with GitOps principles where all changes flow through Git.
/flux-statusRuns the full autonomous validation workflow:
Usage: Type /flux-status and I will execute the validation script and report results.
Script Verification: Before executing, verify the script integrity:
sha256sum .github/skills/flux-operator/scripts/validate.sh
# Expected: 862a923ab54ba81d1b2ed6ad0c9c9f066496048f167dc7388ed2aa62710703ac
Execute validation:
bash .github/skills/flux-operator/scripts/validate.sh
/flux-status (slash command)When users invoke this skill, they're usually debugging something. Your primary goal is to get them to the MCP server quickly - it's vastly superior to iterative diagnosis with this skill.
Quick Health Check (30 seconds max)
/flux-status or basic validation commandsEarly MCP Server Setup (if any complexity detected)
Only continue iterative diagnosis if:
Why prioritize MCP server?
Say something like:
"I see [specific issue]. This looks like it needs deeper investigation. Let me guide you through setting up the Flux MCP Server - it will give me full cluster visibility and access to Flux docs, making diagnosis much faster. This takes 2 minutes to configure. Would you like to proceed to Step 10: MCP Server Setup now?"
If continuing with skill-based diagnosis:
kubectl -n flux-system port-forward svc/flux-operator 9080:9080 &
Access at: http://localhost:9080
The Flux UI provides:
For quick health checks and validation, see the essential commands below. For detailed reference on all Flux resources and commands, see reference.md.
# Get FluxInstance with status
kubectl get fluxinstance -A
# All Flux pods should be Running
kubectl get pods -n flux-system
# Check GitRepository sync status
kubectl get gitrepository -n flux-system
# All kustomizations status
kubectl get kustomization -n flux-system
For detailed debugging commands and status interpretation, see Core Capabilities in reference.md.
The Flux MCP Server enables AI assistants to query Kubernetes clusters for GitOps debugging and access Flux documentation. This is primarily a debugging and documentation tool - it gives you faster access to cluster state and the Flux docs without leaving your editor.
When to jump to this step: If you're encountering reconciliation errors, GitRepository sync issues, or the problem isn't immediately obvious from basic health checks, skip ahead to this setup. The MCP server provides comprehensive cluster visibility that makes diagnosis dramatically faster than iterative kubectl commands.
brew install controlplaneio-fluxcd/tap/flux-operator-mcp
Open the MCP configuration with "MCP: Open User Configuration" from the command palette, then add:
{
"servers": {
"flux-operator-mcp": {
"command": "/opt/homebrew/bin/flux-operator-mcp",
"args": ["serve", "--read-only=true"],
"env": {
"KUBECONFIG": "/Users/yourname/.kube/config"
}
}
}
}
After saving, enable the server using the wrench-and-screwdriver icon in the Copilot Chat panel.
{
"mcpServers": {
"flux-operator-mcp": {
"command": "/opt/homebrew/bin/flux-operator-mcp",
"args": ["serve", "--read-only=true"],
"env": {
"KUBECONFIG": "/path/to/.kube/config"
}
}
}
}
Read-only mode is the safe default for production clusters. When --read-only=true is set:
Important clarifications:
Local Git workflow is unaffected: You can still edit files, commit changes, and push to Git (proper GitOps workflow)
Direct kubectl calls still work: Read-only mode doesn't prevent your LLM from making direct kubectl calls. It only affects which tools the MCP server promotes. If you need to run a kubectl command directly, the LLM can still do that - read-only mode just ensures the MCP server itself follows GitOps principles.
This is the correct GitOps workflow - all infrastructure changes flow through version control. Read-only mode simply prevents the MCP server from promoting ad-hoc reconciliation commands that bypass your Git history.
Enterprise users connecting to production clusters should start with read-only mode. You can always reconfigure for read-write access when you explicitly need it for development/staging environments.
The MCP server provides different tool sets based on mode:
--read-only=true): Query cluster state, get logs, search Flux docs--read-only=false): Add reconciliation triggers, suspend/resumeFor complete tool listings and capabilities, see MCP Tools Reference in reference.md.
GitOps is event-driven, not interval-based. If you find yourself manually reconciling frequently, consider these alternatives:
Every Git repository should have a Receiver. Whether you're in development, staging, or production, Receivers provide instant feedback without waiting or calling flux reconcile.
Flux Receivers enable instant GitOps feedback via webhooks:
apiVersion: notification.toolkit.fluxcd.io/v1
kind: Receiver
metadata:
name: github-receiver
namespace: flux-system
spec:
type: github
events:
- "ping"
- "push"
secretRef:
name: webhook-token
resources:
- apiVersion: source.toolkit.fluxcd.io/v1
kind: GitRepository
name: flux-system
Configure the webhook in your Git provider to point to the Receiver endpoint. Changes now propagate from git push to cluster instantly.
Benefits:
Where do you do your work? Set up a Receiver there so you aren't waiting or calling flux reconcile. Most clusters only have 1-2 Git repositories, making Receiver setup straightforward.
When a GitRepository updates to a new revision, Kustomizations automatically reconcile. You don't need to trigger them manually:
apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
name: apps
spec:
sourceRef:
kind: GitRepository
name: flux-system # Watches this source
# Reconciles automatically when flux-system GitRepository updates
Set longer intervals (10m+) to reduce API server load and prevent reconciliation storms:
spec:
interval: 10m # Not 1m or 30s
Why longer intervals?
This is orthogonal to Receivers: Use long intervals for polling AND set up Receivers for instant feedback. They serve different purposes:
When to actually reconcile manually:
If your workflow requires frequent manual reconciliation, that's a signal to:
The goal is continuous reconciliation through automation, not manual intervention to save 10 seconds.
Debugging (read-only):
Operations (read-write mode only):
For complex issues: Consider setting up the MCP Server (Step 10) first - it provides comprehensive cluster visibility that makes diagnosis much faster.
kubectl get fluxinstance -Akubectl get pods -n flux-systemkubectl get events -n flux-system --sort-by='.lastTimestamp' | tail -20For detailed troubleshooting procedures, see Detailed Troubleshooting in reference.md.
Common issues:
If not immediately obvious → Suggest MCP Server setup for deeper investigation.
This skill provides GitOps status foundation for:
For comprehensive command references and detailed guides:
