Introduction
Kubernetes troubleshooting usually starts with the same routine.
You run commands.
You check pod status.
You describe resources.
You inspect events.
You read logs.
Then you try to connect the dots manually.
That works, but it takes time.
This is where K8sGPT becomes interesting.
K8sGPT is an AI-powered tool designed to scan Kubernetes clusters, diagnose issues, and explain problems in simple language. Its official site describes it as a tool that helps diagnose and fix Kubernetes issues using intelligent insights and automated troubleshooting.
The goal is not to replace kubectl.
The goal is to make troubleshooting faster.
What Is K8sGPT?
K8sGPT is a Kubernetes diagnostic tool powered by AI.
It analyzes your cluster state and provides explanations for possible issues.
Instead of only showing raw Kubernetes output, it tries to explain what the problem means.
The K8sGPT documentation describes it as a tool that combines Kubernetes expertise with AI to help manage and troubleshoot clusters more effectively.
Why This Matters for DevOps Engineers
In real environments, Kubernetes issues are not always obvious.
A pod may be stuck in Pending.
A deployment may fail rollout.
A service may have no endpoints.
A PVC may remain unbound.
A node may become NotReady.
Traditional debugging still works, but it requires experience.
K8sGPT helps by giving a first layer of analysis.
Traditional Kubernetes Debugging Flow
Usually, we troubleshoot like this:
kubectl get pods -n <namespace>
kubectl describe pod <pod-name> -n <namespace>
kubectl logs <pod-name> -n <namespace>
kubectl get events -n <namespace>
This is still important.
But the engineer must manually understand the output.
K8sGPT adds AI-powered interpretation on top of this flow.
What K8sGPT Can Help With
K8sGPT can help with:
- Cluster issue analysis
- Pod troubleshooting
- Kubernetes resource inspection
- Plain-English explanations
- AI-assisted recommendations
- Integration with multiple AI providers
The official K8sGPT site lists features such as AI-powered analysis, data anonymization, support for multiple AI providers, and auto remediation.
Important Safety Note
Before using tools like this, only run them against clusters where you are authorized to inspect resources.
The K8sGPT getting started guide specifically advises using K8sGPT only on environments where you are authorized to modify Kubernetes resources.
For production clusters, start with read-only analysis.
Do not enable automatic remediation unless your team has reviewed and approved that workflow.
Step 1: Install K8sGPT
For Linux or macOS with Homebrew, install K8sGPT using:
brew tap k8sgpt-ai/k8sgpt
brew install k8sgpt
The official installation documentation provides Homebrew installation steps for Linux and macOS.
Step 2: Verify Installation
After installation, verify that K8sGPT is working.
k8sgpt version
The K8sGPT installation guide includes k8sgpt version as the verification command.
If the version is displayed, the CLI is installed correctly.
Step 3: Make Sure kubectl Works First
K8sGPT reads your Kubernetes cluster state, so your kubeconfig must already be working.
Before using K8sGPT, validate normal Kubernetes access.
kubectl cluster-info
kubectl get nodes
kubectl get pods -A
If these commands fail, fix your Kubernetes access first.
K8sGPT cannot analyze the cluster properly if your kubeconfig or context is wrong.
Step 4: Authenticate K8sGPT with an AI Provider
K8sGPT supports multiple AI providers, including OpenAI, Azure, Google, Amazon, and local models according to the official overview.
The getting started guide shows authentication with OpenAI using k8sgpt generate and k8sgpt auth add.
Example flow:
k8sgpt generate
k8sgpt auth add --backend openai --model gpt-4o-mini
After this, K8sGPT can use the configured AI backend for explanations.
Step 5: Run Basic Cluster Analysis
Once configured, run:
k8sgpt analyze
The K8sGPT CLI reference lists k8sgpt analyze as the command used to analyze Kubernetes clusters. [k8sgpt.ai]
This command scans the cluster and returns detected issues with explanations.
Step 6: Analyze a Specific Namespace
In real environments, you may not want to scan everything.
You may only want to analyze one namespace.
k8sgpt analyze --namespace <namespace>
The CLI reference includes namespace filtering using the --namespace flag.
This is useful when you only have access to a specific namespace or want to debug one application area.
Real Scenario 1: Pod Stuck in Pending
A common Kubernetes issue is a pod stuck in Pending.
Traditional debugging starts like this:
kubectl get pods -n dev
kubectl describe pod <pod-name> -n dev
kubectl get pvc -n dev
A typical reason could be insufficient resources or an unbound PVC.
With K8sGPT, you can run:
k8sgpt analyze --namespace dev
Example style of useful interpretation:
Issue:
Pod is stuck in Pending state.
Possible Cause:
PersistentVolumeClaim is not bound.
Suggested Checks:
kubectl get pvc -n dev
kubectl describe pvc <pvc-name> -n dev
kubectl get storageclass
This saves time because it points directly to the storage path instead of forcing you to inspect everything manually.
Real Scenario 2: CrashLoopBackOff
Another common issue is CrashLoopBackOff.
Traditional commands:
kubectl get pods -n dev
kubectl logs <pod-name> -n dev
kubectl logs <pod-name> -n dev --previous
kubectl describe pod <pod-name> -n dev
K8sGPT analysis:
k8sgpt analyze --namespace dev
Example output style:
Issue:
Container is restarting repeatedly.
Possible Cause:
Application startup failure or missing configuration.
Suggested Checks:
kubectl logs <pod-name> -n dev --previous
kubectl describe pod <pod-name> -n dev
kubectl get configmap -n dev
kubectl get secret -n dev
This does not replace manual debugging.
It reduces the first layer of guesswork.
Real Scenario 3: Service Has No Endpoints
Sometimes the service exists but traffic is not reaching pods.
Traditional commands:
kubectl get svc -n dev
kubectl get endpoints -n dev
kubectl describe svc <service-name> -n dev
K8sGPT can help point out service-to-pod mismatch patterns.
Example interpretation:
Issue:
Service has no endpoints.
Possible Cause:
Service selector does not match pod labels.
Suggested Checks:
kubectl get pods -n dev --show-labels
kubectl describe svc <service-name> -n dev
kubectl get endpoints <service-name> -n dev
This is useful because service issues often look like networking problems, but the root cause may be a selector mismatch.
Real Scenario 4: Node NotReady
For node-level issues, engineers usually start with:
kubectl get nodes
kubectl describe node <node-name>
kubectl get events -A
K8sGPT can help summarize what to inspect based on cluster state.
Example output style:
Issue:
Node is marked NotReady.
Possible Cause:
Kubelet issue, resource pressure, or node connectivity problem.
Suggested Checks:
kubectl describe node <node-name>
kubectl get events -A --sort-by=.metadata.creationTimestamp
Check kubelet status on the node
This is helpful during on-call because the first diagnosis becomes faster.
Using Output Formats
K8sGPT can output analysis in different formats such as text, json, and yaml according to the CLI reference.
Example:
k8sgpt analyze --format json
This can be useful if you want to store results or integrate them into another workflow.
K8sGPT with MCP and AI Assistants
K8sGPT also supports Model Context Protocol functionality, where it can expose Kubernetes operations as tools, resources, and prompts for AI assistants. The official K8sGPT site mentions MCP support and shows serve commands for MCP modes.
Example commands shown by K8sGPT:
k8sgpt serve --mcp
k8sgpt serve --mcp --mcp-http --mcp-port 8089
This is more advanced and can be explored after you are comfortable with normal CLI-based analysis.
What K8sGPT Should Not Be Used For Blindly
K8sGPT is helpful, but it should not be treated as an automatic production decision maker.
Avoid blindly using AI output for:
- deleting resources
- changing production workloads
- modifying RBAC
- applying remediation without review
- changing storage resources without validation
The official site mentions auto remediation as a feature, but in production environments this should be used carefully with proper controls.
Best Practice Workflow
A safe workflow looks like this:
1. Run kubectl checks
2. Run k8sgpt analyze
3. Review AI explanation
4. Validate manually
5. Apply fix only after confirmation
K8sGPT should support your troubleshooting process.
It should not replace engineering judgment.
Where K8sGPT Fits in Real DevOps Work
K8sGPT is useful for:
- beginners learning Kubernetes
- DevOps engineers during debugging
- SRE teams doing first-level triage
- platform teams reviewing common issues
- teams building AI-assisted operations workflows
The K8sGPT GitHub organization describes K8sGPT as scanning Kubernetes clusters, diagnosing and triaging issues in simple English, with SRE experience codified into analyzers.
Final Thought
Kubernetes troubleshooting is not going away.
You still need to understand pods, deployments, nodes, services, PVCs, and events.
But AI tools like K8sGPT can reduce the time spent connecting signals manually.
Instead of replacing kubectl, K8sGPT works best as a layer above it.
It turns raw cluster symptoms into easier-to-understand explanations.
🚀 InfraDecode Takeaway
K8sGPT brings AI-assisted troubleshooting to Kubernetes by scanning cluster state and explaining issues in plain language.
It is useful for faster diagnosis, especially for common problems like Pending pods, CrashLoopBackOff, missing endpoints, and node issues.
Use it as a debugging assistant, not as an automatic production fixer.
The best workflow is still simple: observe with kubectl, analyze with K8sGPT, validate manually, then fix carefully.
Discover more from
Subscribe to get the latest posts sent to your email.