KubeSage

CLI tool that analyzes Kubernetes manifests, predicts deployment failures, auto-fixes config issues with AI, and debugs runtime pod failures.

Install

git clone https://github.com/PavvanPradeep/KubeSage.git
cd KubeSage
make install

Requires Go 1.25+.

Commands

analyze

Check manifests for configuration problems before applying them.

kubesage analyze deployment.yaml
kubesage analyze manifests/*.yaml -o json
kubesage analyze deployment.yaml --rules-dir ./my-rules

Checks for: latest image tags, missing resource limits, missing probes, privileged containers, root containers, deprecated API versions, broken service selectors, missing ConfigMaps/Secrets/Ingress targets.

--rules-dir loads additional YAML-defined rules from a directory on top of the built-in ones.

Exits 1 if any HIGH or CRITICAL issue is found.

---

predict

Score the deployment risk of a manifest set. Combines static analysis, dependency graph checks, and optionally live cluster validation.

kubesage predict deployment.yaml
kubesage predict deployment.yaml --kubeconfig ~/.kube/config

Exits 1 if risk is HIGH or CRITICAL.

---

fix

Send issues to an AI model and get back corrected YAML.

export KUBESAGE_AI_PROVIDER=openai
export KUBESAGE_AI_API_KEY=sk-...

kubesage fix deployment.yaml
kubesage fix deployment.yaml --output fixed.yaml --explain

Supported providers: openai, groq, mistral, together, perplexity, deepseek, openrouter, ollama.

For local inference with Ollama (no API key needed):

export KUBESAGE_AI_PROVIDER=ollama
kubesage fix deployment.yaml

---

debug

Diagnose a failing pod or all failing pods in a deployment.

kubesage debug pod api-server-abc123 --namespace production
kubesage debug deployment api-server --namespace production --remediate
kubesage debug pod worker-abc --auto-remediate

Detects: CrashLoopBackOff, OOMKilled, ImagePullBackOff, FailedScheduling, CreateContainerError.

--remediate prompts you to pick an action. --auto-remediate applies safe actions (pod restarts) without prompting.

---

Global flags

Flag	Description
-o, --output-format	Output format: text (default), json, yaml

---

Configuration

Optional .kubesage.yaml in the working directory or home directory:

ai:
  provider: openai
  model: gpt-4o

rules:
  disabled:
    - missing-readiness-probe
  severity_override:
    missing-resource-limits: CRITICAL

remediation:
  max_retries: 3
  cooldown_seconds: 300

The AI API key is never read from this file — use KUBESAGE_AI_API_KEY env var only.

---

Development

make build    # build binary
make test     # run all tests
make vet      # go vet
make install  # install to /usr/local/bin
make clean    # remove binary