k8sgpt: a CLI that scans Kubernetes clusters and explains failures in plain English

What k8sgpt is for, and who ends up using it

The README describes k8sgpt as a tool for scanning Kubernetes clusters, diagnosing, and triaging issues in simple English. That sentence is doing more work than it looks. The tool is not a monitoring system and not a remediation agent. It is a diagnostic pass you run when you already suspect something is wrong, or when you want a periodic sweep that turns a wall of Kubernetes status fields into sentences a human can read.

The intended user is an SRE or platform engineer who knows Kubernetes well enough to be suspicious of summaries. k8sgpt ships analyzers that encode SRE experience, in the project's own phrasing, and the analyzers decide what gets looked at. The AI layer sits downstream of that: it explains findings, it does not discover them. This ordering matters when you evaluate the tool, because it means the quality of the scan is bounded by the analyzers, not by the model you choose.

Where it fits well: a cluster where pods are in CrashLoopBackOff, services have no endpoints, or ingresses are misconfigured, and you want the relevant status fields pulled together before you start reading events by hand. Where it fits badly: anything that requires knowing what changed. k8sgpt reads current state. The README does not describe any historical comparison, so the tool cannot tell you that a deployment was healthy an hour ago.

How the analyzers and AI backends fit together

The architecture visible in the repository is a Go CLI built on cobra and viper, with client-go talking to the cluster and a set of provider SDKs behind the AI layer. The go.mod file lists the shape of that provider layer directly: go-openai, the Anthropic SDK, the AWS Bedrock and Bedrock Runtime clients, the Cohere Go client, Google Vertex AI, IBM watsonx, and the ollama package. The README states out of the box integration with OpenAI, Azure, Cohere, Amazon Bedrock, Google Gemini and local models.

Data flow is straightforward. An analyzer queries the Kubernetes API for a specific class of object, extracts the fields that indicate a problem, and produces a structured finding. The AI backend receives that finding and returns an explanation. The README also documents a flag that changes the retrieval side rather than the model side: k8sgpt analyze --with-doc fetches the official Kubernetes documentation to accompany the result, with or without the explain flag.

The consequence of this design is that switching providers changes the prose you get back, not the set of problems detected. If an analyzer never inspects a particular resource type, no model will surface it. The go.mod dependency list is also worth reading as a maintenance signal: supporting six-plus providers means six-plus SDKs that move independently, which is visible in how frequently releases appear.

Installing k8sgpt and running a first scan

The README gives Homebrew as the primary path on Linux and macOS. The tap form is documented as an alternative to the single-command install.

brew install k8sgpt

For RPM-based distributions the README publishes architecture-specific packages on the release page, and the 64-bit form is shown as:

sudo rpm -ivh https://github.com/k8sgpt-ai/k8sgpt/releases/download/v0.4.39/k8sgpt_amd64.rpm

Debian and Ubuntu users get the equivalent .deb, downloaded and installed with dpkg. Alpine users get an .apk installed with apk add --allow-untrusted. Windows users download a binary from the releases tab and add its location to PATH. There is a documented failure mode for Homebrew on WSL and Linux: the formula may try to build from source and fail on a missing compiler. The README's own fix is to install build-essential rather than gcc.

Once the binary is on PATH, the default provider is OpenAI. The README says you can run k8sgpt generate to open a browser link for creating a key, then register it:

k8sgpt auth add

The README notes you can supply the key non-interactively with the --password flag. Filters control which analyzers run, and by default all filters execute during analysis:

k8sgpt filters

Then the scan itself, first without and then with explanation:

k8sgpt analyze
k8sgpt analyze --explain

What you should see is a list of findings from the active filters, and with --explain, model-generated commentary on each. If you get findings but no explanation, the auth step is the first thing to check, since analysis and explanation are separable stages.

The OpenAI default is the real adoption constraint

The README states plainly that the default AI provider is OpenAI and that you need to generate an API key to use it. That default is convenient and also the single biggest reason teams stop evaluating k8sgpt. Sending cluster diagnostics to an external API means object names, namespaces, image references, and error strings leave your network. For many organizations that is a non-starter, and no amount of analyzer quality changes the answer.

The local path exists. The ollama package appears in go.mod, the README lists local models among the supported integrations, and there is a SUPPORTED_MODELS.md file in the repository root. What the README does not do is walk through a local-model setup with the same concreteness it gives the OpenAI flow, which is a gap: the users who most need the local option are the ones who get the least guidance. Expect to read the documentation site rather than the README for that configuration.

A second limitation is scope. k8sgpt diagnoses; it does not fix. There is no rollback, no patch application, no reconciliation loop in what the README describes. You read the output and act. For anyone hoping for an automated remediation tool, this is the wrong category of software, and the sister project referenced in the README for managing agents in Kubernetes is a separate codebase rather than a feature of this one.

k8sgpt versus kubectl and versus kagent

The most common comparison is against plain kubectl, and it is not a close one. kubectl describe pod and kubectl get events give you raw fields; you supply the interpretation. k8sgpt supplies a first interpretation and then optionally a model-written explanation on top. The trade-off is that you have exchanged a deterministic, auditable output for a generated one. When you need to be certain about a field value, kubectl remains the right tool, and k8sgpt is a triage layer in front of it rather than a replacement.

The other comparison that comes up is kagent, which is a different kind of project. Where k8sgpt is a CLI you invoke and read from, an agent framework is oriented toward acting on the cluster through tool use. If your goal is autonomous operation, k8sgpt's read-and-explain model will feel like a dead end, and that is by design rather than by omission. If your goal is a human-readable diagnosis you review before touching anything, the narrower scope is an advantage.

There is also the operator. The README points to k8sgpt-operator for installing within a cluster and describes that mode as ideal for continuous monitoring, with integration into existing monitoring such as Prometheus and Alertmanager. That is a genuinely different deployment: the CLI is something a person runs, the operator is something that runs continuously. Choosing between them is the first real decision, and the README treats them as separate installs rather than one product with two modes.

MCP integration and the Claude Desktop path

The README documents an MCP server mode and states that the Claude Desktop integration requires k8sgpt v0.4.14 or later. The prerequisites listed are a Homebrew install of a recent enough version, Claude Desktop itself, and a configured AI backend via k8sgpt auth. The setup section then shows starting the K8sGPT MCP server, though the README excerpt cuts off mid-command.

What this mode changes is who initiates the scan. Instead of you running k8sgpt analyze in a terminal, a desktop assistant calls into the cluster through the MCP server. The analyzers and the backend configuration are the same; the interface is different. For engineers already working inside Claude Desktop, that removes a context switch. For everyone else it adds a moving part, and the version floor means an older binary will simply not work.

The repository root contains an MCP.md file alongside the README, which suggests the protocol details live there rather than in the main document. Given that the README's own setup instructions are incomplete, MCP.md is where to look before assuming the integration is broken. This is the least mature-looking part of the documented surface, and it is also the part most likely to change between releases.

Licence, releases and what upgrades cost you

k8sgpt is Apache-2.0, confirmed both by the repository licence file and the badge in the README. Apache-2.0 permits commercial use and modification and includes an explicit patent grant, which matters for organizations that need that clarity before shipping a tool internally. It does not, of course, cover the model providers you connect it to: your OpenAI, Bedrock, Gemini or Azure usage is governed by those vendors' terms, and the licence on this repository says nothing about them. That distinction is easy to miss when a tool advertises multi-provider support.

The release cadence is high. The recent releases list shows v0.4.37, v0.4.38 and v0.4.39 within roughly three weeks, and the last push to the repository was on 2026-09-14, the same day as v0.4.39. Frequent patch releases are normal for a project tracking fast-moving provider SDKs, and the go.mod file shows exactly why: OpenAI, Anthropic, Cohere, AWS, Google and Ollama libraries all version independently, and any of them can force a compatibility release.

Practically, that cadence sets your upgrade cost. Pin a version in CI rather than tracking latest, because a patch bump can change provider behaviour without changing the command surface. The Makefile builds with CGO disabled and injects version, commit and date via ldflags, so a locally built binary reports its own provenance, which is useful when you need to confirm which build produced a given scan. Release automation runs through release-please, judging by the manifest and config files in the repository root.

Editorial conclusion

Adopt k8sgpt if you operate Kubernetes and want a fast, repeatable first pass over failing workloads, and if you are willing to choose a backend deliberately rather than accept the OpenAI default. Do not adopt it if you cannot send cluster diagnostics to an external model provider and will not run a local one, or if you need continuous in-cluster monitoring and are not prepared to install the separate k8sgpt-operator. Before rolling it out, verify three things on a non-production cluster: that your chosen provider authenticates through k8sgpt auth add, that the default filter set produces findings you consider actionable rather than noise, and that your cluster's RBAC allows the read access the analyzers need.

Frequently asked questions

Official sources

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