k8sgpt: Kubernetes Cluster Diagnostics with AI

Automated Kubernetes troubleshooting with AI explanations

k8sgpt automates the first step of Kubernetes troubleshooting: finding what is broken. When pods fail to start, services do not route, or persistent volumes are stuck, k8sgpt scans the cluster and uses AI to explain what happened and why. It outputs plain English instead of raw Kubernetes objects. The tool has SRE experience codified into its analyzers, reflecting real-world debugging patterns.

The tool runs either as a standalone CLI or as an operator you deploy inside your cluster. The CLI model suits operators who connect on demand. The operator model watches your cluster continuously and can feed alerts into Prometheus or Alertmanager, which makes it useful for teams that want every failure surface a diagnostic message without manual runs.

k8sgpt collects facts using built-in analyzers, each focusing on one kind of Kubernetes object. The pod analyzer checks for crash loops, image pull failures, and resource starvation. The replica set analyzer detects mismatches between desired and actual count. The ingress analyzer finds broken backend targets. The persistent volume claim analyzer identifies stuck provisioning. The service analyzer checks connectivity. The event analyzer scans cluster events for warnings. The statefulset analyzer watches for rolling update stalling. Run `k8sgpt filters` to see a menu of all analyzers and toggle them on or off based on your cluster's needs.

Multiple AI backends and architecture

k8sgpt's architecture is straightforward: collect Kubernetes facts, send them to an AI, and return the AI's answer. The tool does not generate diagnoses on its own; it relies entirely on the AI backend for interpretation. The default AI backend is OpenAI, which requires an API key, but the project supports Azure, Cohere, Amazon Bedrock, Google Gemini, Anthropic, IBM Watsonx, and local models through Ollama. This breadth of support lets you choose an AI provider based on your compliance requirements, latency needs, or cost optimization.

Each analysis call hits the API and incurs a cost. How much depends on the size of your cluster and the AI model you choose. The pricing varies by provider, so you will need to consult your chosen backend's pricing page. You can run `k8sgpt generate` to open a browser to generate an OpenAI API key automatically.

The project includes a Model Context Protocol (MCP) server, which lets you query a running k8sgpt instance from Claude Desktop without running the command line. Start the MCP server with `k8sgpt serve --mcp` and configure Claude to connect to it. Then ask Claude to analyze your cluster: you can say "Analyze my Kubernetes cluster" or "Show me any issues in the default namespace." This integration brings cluster analysis into Claude's conversational interface, combining natural language with k8sgpt's specialized analyzers.

Installing and running your first analysis

On macOS or Linux, install via Homebrew:

brew install k8sgpt

Windows users download the latest binary from the GitHub releases page and add it to their PATH. Debian, RPM, and Alpine packages are also available via direct download URLs. The tool is written in Go and requires Go 1.26.3 or later to build from source. Installation is straightforward across platforms.

Once installed, authenticate with an AI backend:

k8sgpt auth add

You can provide the password directly using the `--password` flag. Run an analysis across your entire cluster:

k8sgpt analyze

This scans all active analyzers and prints findings. Add the `--explain` flag for more detail:

k8sgpt analyze --explain

You can also ask for links to official Kubernetes documentation:

k8sgpt analyze --with-doc

The output of these commands is plain text suitable for reading or piping to other tools.

Running k8sgpt inside your cluster with the operator

For continuous monitoring instead of manual runs, install the k8sgpt operator from the separate k8sgpt-operator repository. The operator runs as a deployment in your cluster and watches for problems without you having to connect and run commands.

The operator integrates with Prometheus and Alertmanager. When an analyzer finds an issue, the operator can fire a Prometheus alert, which your existing alerting rules can then route to your team's notification channel. This makes k8sgpt useful for teams that already monitor their infrastructure and want to enrich alerts with AI-driven context. The operator can push alerts to external services, and Helm charts in the project provide configuration options for that integration. This setup enables AI-powered diagnostics to become part of your standard observability stack.

Deploy and configure the operator through Helm charts, which the project provides.

The API key barrier and cluster access requirements

k8sgpt cannot run without an API key to an AI service. If your organization blocks external API calls or requires approval before spending on cloud services, you will need to get that approval first. The cost is not fixed and depends on your cluster size and how often you run analysis. Some organizations may find the API cost prohibitive if they run large clusters with frequent analyses.

k8sgpt also requires read access to your Kubernetes cluster. It queries pods, services, events, ingress resources, and other objects. If you do not have permission to read the cluster, the tool will fail. In a restrictive environment where workloads are isolated by namespace and only some teams can read across namespaces, you may need to run k8sgpt separately for each namespace or request elevated read permissions. The tool connects using your local kubeconfig, so it respects your existing Kubernetes authentication and authorization rules.

How k8sgpt differs from kubectl ai

kubectl ai is a plugin that answers questions about Kubernetes using an LLM, but it works differently from k8sgpt. kubectl ai takes a command you type and uses AI to interpret it or suggest fixes. k8sgpt, on the other hand, proactively scans your cluster and reports what it finds without waiting for user input.

k8sgpt is also a wrapper around a set of analyzers, not a general-purpose AI chat. If you want to ask the tool a custom question about your cluster, you cannot do that through the CLI; you can only run its built-in analyses. For custom queries, use the MCP server and Claude Desktop instead. The project also maintains sister projects like sympozium for managing agents in Kubernetes, suggesting a broader ecosystem of tools.

Building custom analyzers and active maintenance

k8sgpt has a set of built-in analyzers but you can write your own. This means if your cluster has custom resources or domain-specific failure patterns, you can extend k8sgpt with custom analysis logic. The documentation includes a guide on creating custom analyzers, making the tool adaptable to specialized environments.

The last push to the repository was on 2026-09-27, two days ago. The project releases regularly, with three releases between 2026-08-27 and 2026-09-14. It holds a Core Infrastructure Initiative best practices badge, confirming its security posture. The license is Apache 2.0. The project is written in Go and includes Helm charts for Kubernetes deployment, making it straightforward to install and update.

Editorial conclusion

k8sgpt is for teams running Kubernetes who want to surface issues faster and understand them without deep expertise in Kubernetes internals. Skip this if you do not have permission to query your cluster or cannot bear the cost of an external API. Before adopting it, verify that your chosen AI backend covers your geographic region and complies with your data policies.

Frequently asked questions

Official sources

1. k8sgpt-ai/k8sgpt on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases