k8sgpt-operator: running K8sGPT inside the cluster as a custom resource
Automatic SRE Superpowers within your Kubernetes cluster
At a glance
- What is it?
- The k8sgpt-operator turns K8sGPT from a CLI you run by hand into a controller-managed workload driven by a K8sGPT custom resource, with an opt-in alpha path that can repair image-pull failures. It is for cluster operators who already accept an LLM in their diagnostic loop.
- Who is it for?
- Adopt it if you want K8sGPT results as Kubernetes objects you can query, sink to Slack, or point at remote clusters through a kubeconfig secret, and if you are comfortable sending cluster diagnostics to an LLM backend. Do not adopt it if you cannot accept an external model seeing that data, or if you need auto-remediation to be more than alpha.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository received new commits within the last day.
- What is it written in?
- Mainly Go, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
What k8sgpt-operator adds on top of the K8sGPT CLI
K8sGPT itself scans a cluster and explains failures. Run as a CLI, that means someone has to remember to run it, and the output lives in a terminal buffer. The operator changes the deployment model: you install a controller, and from then on K8sGPT is described by a K8sGPT custom resource in the core.k8sgpt.ai/v1alpha1 API group. The README states the operator "will allow you to create a custom resource that defines the behaviour and scope of a managed K8sGPT workload."
The audience is platform and SRE teams that already run controllers and want diagnostics to arrive as cluster state rather than as a command someone types. That framing has a cost worth naming: a CLI run is a deliberate act with a human in the loop, while an operator reconciles continuously and writes objects into your cluster. You are trading a manual step for a persistent workload that holds an API key and talks to a model provider.
Scope is set per resource, not globally. The sample spec shows filters, integrations, a sink, and AI backend settings all living on the K8sGPT object, so two teams can run two differently configured instances in the same cluster.
The reconcile path from K8sGPT object to Result objects
The architecture follows the standard controller-runtime shape visible in go.mod, which pins sigs.k8s.io/controller-runtime v0.21.0 alongside k8s.io/api and k8s.io/client-go at v0.33.3. A manager binary built from cmd/main.go watches K8sGPT resources. When one appears, the operator creates a Deployment running the K8sGPT image named in the spec, using the repository and version fields to pick the image.
Analysis output comes back as Result objects in the same namespace. The README's example shows a Result whose spec.details carries prose explaining an error and a suggested fix, in that case a Service with no endpoints that should have carried a control-plane=controller-manager label. So the data flow is: operator creates the workload, the workload scans, findings land as custom resources you can read with kubectl.
The Dockerfile shows the operator itself is a single static Go binary on gcr.io/distroless/static:nonroot running as user 65532:65532, with CGO disabled. That matters for supply-chain review: no shell, no package manager, and no root in the operator container.
The AI backend is pluggable at the spec level. The sample sets backend: openai with model: gpt-4o-mini and a secret reference, and the commented fields list backOff, anonymized, language, and proxyEndpoint. The anonymized flag and the proxyEndpoint option are the two knobs that matter most in restricted networks, since one strips identifying data before it leaves and the other routes the call through an HTTP/HTTPS proxy.
Installing the k8sgpt operator Helm chart and applying a first K8sGPT resource
The README gives a Helm install against the project's chart repository. Run it and you should end up with a controller deployment in the k8sgpt-operator-system namespace.
helm repo add k8sgpt https://charts.k8sgpt.ai/
helm repo update
helm install release k8sgpt/k8sgpt-operator -n k8sgpt-operator-system --create-namespaceNext, create the secret the operator will read for the model API key. The README uses a literal from an environment variable named OPENAI_TOKEN, and the key inside the secret is openai-api-key.
kubectl create secret generic k8sgpt-sample-secret --from-literal=openai-api-key=$OPENAI_TOKEN -n k8sgpt-operator-systemThen apply the K8sGPT object. The README shows this as a heredoc; the fields that matter are the backend, the model, the secret reference, and the K8sGPT image repository and version.
kubectl apply -f - << EOF
apiVersion: core.k8sgpt.ai/v1alpha1
kind: K8sGPT
metadata:
name: k8sgpt-sample
namespace: k8sgpt-operator-system
spec:
ai:
enabled: true
model: gpt-4o-mini
backend: openai
secret:
name: k8sgpt-sample-secret
key: openai-api-key
noCache: false
repository: ghcr.io/k8sgpt-ai/k8sgpt
version: v0.4.32
EOFAfter the resource is applied, the README says the K8sGPT deployment is installed and Result objects appear after some minutes if the cluster has issues. Read them with the results plural, scoped to the namespace.
kubectl get results -n k8sgpt-operator-system -o json | jq .If nothing shows up, that is not necessarily a failure. Results are only created when the scan finds something to report.
Auto-remediation is alpha, opt-in, and deliberately narrow
The most consequential feature sits behind an explicit warning in the README: auto-remediation is "deliberately alpha and opt-in." The operator can repair selected workload image failures, and the README describes a validated end-to-end path where a provider analyzed an ImagePullBackOff, the operator generated a one-image repair, Kubernetes rolled out the corrected Deployment, and a Mutation object reached Successful.
The safety design is the interesting part, and it is worth quoting precisely because it is the whole argument for the feature: "The LLM never receives write authority: the operator re-fetches the object, calculates the semantic JSON patch itself, allows exactly one approved image path, dry-runs it with the Kubernetes API server, and rejects stale, broad, or unsafe proposals." That is a meaningful boundary. The model produces a suggestion; the operator builds the patch and lets the API server dry-run it.
Two constraints follow. First, owned Pod findings are repaired through their selected owning workload, so the change lands in desired state rather than on an ephemeral Pod. Second, the README directs you to AUTO_REMEDIATION.md for the policy model, supported workload types, audit fields, and operational limits before enabling it. It does not enumerate the supported workload types in the README itself, so the supported set is something you have to go read rather than assume.
Enabling it is a separate apply of a sample manifest. The README gives this command for the valid remediation sample.
kubectl apply -n k8sgpt-operator-system \
-f config/samples/autoremediation/valid_k8sgpt_remediation_sample.yamlProvider setup stays independent of the remediation policy: the README states the operator applies the same safeguards to every backend. That is a good property, because it means switching from OpenAI to another provider does not change the write-path guarantees.
Watching remote clusters through a kubeconfig secret
Multi-cluster support is the feature that most changes how you would deploy this. Instead of installing anything on each workload cluster, you give the K8sGPT resource a kubeconfig reference and the operator reaches out. The README describes the Cluster API case: a provisioned cluster gets a kubeconfig Secret named ${CLUSTERNAME}-kubeconfig in the same namespace, with the data key value, and the operator uses it to monitor the remote cluster.
apiVersion: core.k8sgpt.ai/v1alpha1
kind: K8sGPT
metadata:
name: capi-quickstart
namespace: k8sgpt-operator-system
spec:
ai:
anonymized: true
backend: openai
language: english
model: gpt-4o-mini
secret:
key: api_key
name: my_openai_secret
kubeconfig:
key: value
name: capi-quickstart-kubeconfigThe README flags a security concern directly: a Cluster API generated kubeconfig is bound to the admin user with cluster-admin permissions, and if you want least privilege you must supply a different kubeconfig. Take that seriously. The operator's blast radius on a remote cluster is exactly the permissions of the kubeconfig you hand it, and the convenient option is the over-privileged one.
This design also means the operator runs in the management cluster and holds credentials for every cluster it watches. That is a central point of failure and a central secret store, which is a real trade-off against per-cluster installation.
Where the operator is the wrong choice
If your constraint is that cluster diagnostics must not leave your network, the operator's default path does not fit. The sample configuration sends findings to an OpenAI model. The spec offers anonymized: true and proxyEndpoint, and the README comments show both, but anonymization reduces what is sent rather than keeping it local. If the requirement is absolute, you either point the backend at a model you host and trust, or you do not run this.
The second case is auto-remediation. The README labels it alpha. Alpha, in this project's own words, means the full path has been validated in a live run, not that the policy model is settled. If your change-management process requires a feature to be stable before it touches workloads, leave it off. The operator works fine as a read-only analyzer; remediation is a separate apply.
The third case is a single cluster you look at occasionally. The operator's value comes from continuous reconciliation and from results landing as objects. If a developer runs the K8sGPT CLI against one cluster when something breaks, adding a controller, a CRD, a namespace, a secret, and an image version to track is overhead with no payoff.
One more limitation is documented rather than hidden: the README does not describe rollback behaviour for an applied remediation. The Mutation object records that a change reached Successful, but the README is silent on reverting one. Treat remediation as a forward-only action until you have read AUTO_REMEDIATION.md and confirmed otherwise.
Alternatives and how their approach differs
The obvious alternative is the K8sGPT CLI itself, from the same project. It runs on demand against whatever context you have configured and prints analysis to your terminal. The difference is not capability but lifecycle: the operator runs K8sGPT as a managed Deployment and materializes findings as Result custom resources, while the CLI produces output that disappears when the terminal closes. If you want alerting, history, or a sink to Slack, the operator gives you objects to hang that on. If you want a one-off answer, the CLI is fewer moving parts.
A second comparison is with general-purpose Kubernetes policy and admission controllers. Those intercept objects as they are created or updated and can reject them. The operator does something different: it observes existing failures after the fact, asks a model to interpret them, and only in the alpha remediation path proposes a change. Admission control is preventive and deterministic; k8sgpt-operator is diagnostic and probabilistic. They are complements, not substitutes, and the operator's dry-run gate is the closest it gets to the preventive model.
If your goal is purely to detect drift or enforce configuration, an admission or GitOps reconciliation tool is the right layer. Reach for k8sgpt-operator when the missing piece is explanation: why an ImagePullBackOff happened, or why a Service has no endpoints.
Maintenance cadence, version pinning, and the Apache-2.0 licence
The repository is not archived, and the last push was on 2026-09-14. Releases are frequent but not evenly spaced: v0.2.27 landed on 2026-03-28, then v0.2.28 and v0.2.29 both on 2026-08-13. The release tooling is visible in the repository root, with release-please-config.json and .release-please-manifest.json driving version bumps, and renovate.json handling dependency updates. go.mod targets go 1.26.3 with toolchain go1.26.5, and the Dockerfile builds on golang:1.26-alpine3.23, so the build toolchain is current.
Upgrade cost has two independent axes, and this is the part teams underestimate. The first is the operator chart, installed from charts.k8sgpt.ai. The second is the K8sGPT image the operator deploys, which is pinned in each K8sGPT resource through the repository and version fields. The README's sample pins version: v0.4.32. That means upgrading the operator does not automatically upgrade the analyzer, and you can end up running an old K8sGPT image under a new operator. Treat the version field as something to review on a schedule, not a value you set once.
On licensing: the project is Apache-2.0, and the Dockerfile carries org.opencontainers.image.licenses='Apache-2.0' in its OCI labels. Apache-2.0 includes an explicit patent grant and requires preservation of notices. Note that the operator invokes an external model provider under that provider's own terms, and your API key and data are governed by those terms, not by the operator's licence. That is a factual distinction, not legal advice; get counsel if the data flow matters to your compliance posture.
Editorial conclusion
Adopt it if you want K8sGPT results as Kubernetes objects you can query, sink to Slack, or point at remote clusters through a kubeconfig secret, and if you are comfortable sending cluster diagnostics to an LLM backend. Do not adopt it if you cannot accept an external model seeing that data, or if you need auto-remediation to be more than alpha. Before enabling anything, read AUTO_REMEDIATION.md for the policy model and supported workload types, and check that the ghcr.io/k8sgpt-ai/k8sgpt image tag in your K8sGPT spec matches a version you have reviewed.
Frequently asked questions
How do I install the k8sgpt operator Helm chart?
Add the repository with helm repo add k8sgpt https://charts.k8sgpt.ai/ and run helm repo update, then install with helm install release k8sgpt/k8sgpt-operator -n k8sgpt-operator-system --create-namespace. The README gives exactly these three commands.
Can k8sgpt-operator use Ollama or another local model backend?
The README's sample configuration uses backend: openai with model: gpt-4o-mini, and it points to the sample configurations under config/samples/ for provider-specific manifests. The README does not name Ollama, so check the samples directory for the backends actually supported.
Does k8sgpt-operator fix problems in my cluster automatically?
Only if you enable auto-remediation, which the README describes as deliberately alpha and opt-in. It repairs selected Kubernetes workload image failures, and the LLM never receives write authority: the operator re-fetches the object, builds the semantic JSON patch itself, allows one approved image path, and dry-runs it with the API server.
How do I see the results of a k8sgpt-operator analysis?
Read the Result objects in the operator namespace, for example with kubectl get results -n k8sgpt-operator-system -o json. The README notes results appear after some minutes, and only if there are issues in your cluster.
Can k8sgpt-operator monitor more than one cluster?
Yes. You provide a kubeconfig in the K8sGPT spec, and the README describes the Cluster API convention where a provisioned cluster gets a Secret named ${CLUSTERNAME}-kubeconfig with the data key value. The README warns that the Cluster API generated kubeconfig is bound to the admin user, so supply a least-privilege one if that matters.
Which K8sGPT version does the operator run?
The K8sGPT resource pins it: the sample sets repository: ghcr.io/k8sgpt-ai/k8sgpt and version: v0.4.32. Upgrading the operator chart does not change that field, so the analyzer version is something you maintain per resource.
Community notes