1 line
13 KiB
JSON
1 line
13 KiB
JSON
{"repo": "abhicodeitout/kubeaid", "files": {"README.md": {"26706f3df343f3d3d74a258babf16b81a4ac9dfb": {"t": 1785596419.7653992, "n": 12262, "h": "ecaec43359b224e2", "c": "# KubeAid\n\n[](https://golang.org)\n[]()\n[](LICENSE)\n\nKubeAid is a Kubernetes debugging CLI that analyzes workloads, scores pod health, and gives actionable fix steps.\n\n## Demo\n\n> **KubeAid v0.0.1** — deploying a crash-looping app and running every command end-to-end.\n\n[](./demo/kubeaid-v001-demo.mp4?raw=1)\n\n> 📥 Click the button above to download and play the MP4 video (33s · 1074×872 · H.264)\n\n**What's shown:**\n1. `version` — tool version banner\n2. `context` — active Kubernetes cluster\n3. `kubectl get pods` — crash-looping `kubeaid-demo` app\n4. `crashloops` — auto-detection of all crashing pods\n5. `analyze` — health score 0/100, events, AI hints, Copilot fix steps\n6. `report -f json` — full JSON debug report export\n\n## What You Get\n- App-level diagnosis from pod status, events, logs, and resource hints\n- Health score (0-100) with AI or built-in fallback suggestions\n- Watch mode, threshold-based exit codes, and webhook alerts\n- Report export in text, JSON, and HTML\n- Crash loop inspector with previous container logs\n- TUI with pod selector, logs panel, and context switching\n- Enterprise security controls (validation, redaction, RBAC checks, audit logging)\n- Copilot-style troubleshooting suggestions with AI and pattern fallback\n\n## Quick Start\n\n```sh\ncd kube-debugger\nmake build VERSION=v1.2.0\n./kube-debugger --help\n```\n\nAnalyze one app:\n\n```sh\n./kube-debugger analyze my-app -n default\n```\n\nAnalyze continuously:\n\n```sh\n./kube-debugger analyze my-app --watch --interval 10\n```\n\nFail CI when health is too low:\n\n```sh\n./kube-debugger analyze my-app --exit-code --threshold 80\n```\n\n## Testing\n\nFrom `kube-debugger/`:\n\n```sh\nmake test\n```\n\n`make test` now runs both:\n- `unit-test`: `go test ./...`\n- `smoke-test`: local CLI command and exit-code checks\n\nDuring `make test`, AI execution is intentionally disabled for smoke checks using:\n- `KUBEAID_AI_ADVISOR=off`\n- `KUBEAID_AI_PROVIDER=`\n\nCI/CD pipelines also run with AI disabled. AI suggestions are intended for developer-invoked commands during manual troubleshooting.\n\nRun targets individually:\n\n```sh\nmake unit-test\nmake smoke-test\n```\n\nRun integration tests (tagged, optional for local dev):\n\n```sh\ngo test -tags=integration ./pkg/analyzer -v\n```\n\nRecommended pre-release local check:\n\n```sh\nmake build VERSION=v1.2.0\nmake test\n```\n\n## Install\n\nHomebrew:\n\n```sh\nbrew tap abhicodeitout/tap\nbrew install kube-debugger\n```\n\nGo install:\n\n```sh\nGO111MODULE=on go install github.com/Abhicodeitout/KubeAid/kube-debugger@latest\n```\n\nLocal plugin-style install:\n\n```sh\ncd kube-debugger\nmake install\n```\n\nThis installs both:\n- `~/.local/bin/kube-debugger`\n- `~/.local/bin/kubectl-debug`\n\n## OS Compatibility\n\nKubeAid works on Linux, macOS, and Windows.\n\n| OS | Status | Notes |\n|---|---|---|\n| Linux | Supported | Full CLI support. `report --open` uses `xdg-open` or `$BROWSER`. |\n| macOS | Supported | Full CLI support. `report --open` uses `open` or `$BROWSER`. |\n| Windows | Supported | Full CLI support. `report --open` uses `cmd /c start` or `$BROWSER`. |\n\nRequired on all OS:\n- A working Kubernetes context (`~/.kube/config` or `KUBECONFIG`)\n- `kubectl` installed and configured\n\nOptional by feature:\n- `gh` CLI for `report --create-issue`\n- Ollama for local AI provider (`KUBEAID_AI_PROVIDER=ollama`)\n- Groq API key for cloud AI provider (`KUBEAID_AI_PROVIDER=groq`)\n\nNotes:\n- `make` targets are easiest on Linux/macOS; on Windows, running via WSL or Git Bash is recommended.\n- Browser auto-open depends on an available launcher; set `$BROWSER` to override.\n\n## Core Commands\n\n| Command | Purpose |\n|---|---|\n| `kube-debugger analyze [app-name]` | Analyze an app and print diagnosis |\n| `kube-debugger report [app-name]` | Export report in text/json/html |\n| `kube-debugger crashloops` | Show CrashLoopBackOff pods and previous logs |\n| `kube-debugger history [app-name]` | Show recorded health score history |\n| `kube-debugger tui` | Launch terminal UI |\n| `kube-debugger context list/switch` | Manage kubeconfig context |\n| `kube-debugger bootstrap` | Environment checks and optional Ollama setup |\n\nFull command examples: [kube-debugger/COMMANDS.md](kube-debugger/COMMANDS.md)\n\nRoadmap tracker: [ROADMAP_V2.md](ROADMAP_V2.md)\n\n## Copilot-Style Suggestions\n\nKubeAid includes Copilot-style troubleshooting guidance that produces structured, actionable fix suggestions.\n\n- Detects common failure patterns (CrashLoopBackOff, OOMKilled, ImagePull, probe failures, RBAC, network timeouts, and TLS issues)\n- Provides step-by-step remediation guidance\n- Suggests copy-runnable kubectl commands\n- Includes YAML snippets when configuration fixes are needed\n- Uses AI provider output when available, with automatic pattern-based fallback\n\nSee full details in [kube-debugger/COPILOT.md](kube-debugger/COPILOT.md).\n\n## Advanced Modules\n\nThe repository now includes advanced modules under [kube-debugger/pkg](kube-debugger/pkg) for enterprise expansion:\n\n- [kube-debugger/pkg/alerts](kube-debugger/pkg/alerts): alert manager, channel abstraction, deduplication, throttling\n- [kube-debugger/pkg/metrics](kube-debugger/pkg/metrics): metrics collection, retention, trend and anomaly helpers\n- [kube-debugger/pkg/optimizer](kube-debugger/pkg/optimizer): cost optimization suggestions\n- [kube-debugger/pkg/prediction](kube-debugger/pkg/prediction): predictive failure analysis helpers\n- [kube-debugger/pkg/remediation](kube-debugger/pkg/remediation): auto-remediation handler framework\n- [kube-debugger/pkg/policy](kube-debugger/pkg/policy): policy and compliance validation primitives\n- [kube-debugger/pkg/integrations](kube-debugger/pkg/integrations): integration hub abstractions (Slack, PagerDuty, Email, Datadog)\n- [kube-debugger/pkg/multicluster](kube-debugger/pkg/multicluster): multi-cluster management helpers\n- [kube-debugger/pkg/comparison](kube-debugger/pkg/comparison): cross-environment comparison utilities\n- [kube-debugger/pkg/rules](kube-debugger/pkg/rules): custom rule engine primitives\n- [kube-debugger/pkg/reporting](kube-debugger/pkg/reporting): markdown/html/json report generation helpers\n\nCurrent status:\n- These modules compile and are ready for integration.\n- They are package-level building blocks and are not exposed as top-level CLI commands yet.\n\n## Common Workflows\n\nAlert when health drops:\n\n```sh\n./kube-debugger analyze my-app \\\n\t--alert-webhook https://example.com/hook \\\n\t--alert-threshold 75\n```\n\nScan across all namespaces:\n\n```sh\n./kube-debugger analyze my-app -A\n```\n\nExport and diff reports:\n\n```sh\n./kube-debugger report my-app -f json -o current.json\n./kube-debugger report my-app --diff previous.json\n```\n\nOpen HTML report in browser:\n\n```sh\n./kube-debugger report my-app -f html -o report.html --open\n```\n\nCreate a GitHub issue from report data:\n\n```sh\n./kube-debugger report my-app --create-issue\n```\n\nInspect crash loops:\n\n```sh\n./kube-debugger crashloops -n default\n```\n\nView score history:\n\n```sh\n./kube-debugger history my-app -n default\n```\n\n## Security\n\nKubeAid includes enterprise-grade security features to protect your cluster data and operations.\n\n### Features\n\n- **Input Validation**: Validates all user inputs against Kubernetes naming conventions (RFC 1123)\n- **Secret Redaction**: Automatically redacts API keys, tokens, passwords, and credentials from logs and output\n- **Audit Logging**: Logs all operations with timestamps, users, commands, and results for compliance and troubleshooting\n- **RBAC Checks**: Verifies user permissions before executing operations\n- **TLS/Certificate Validation**: Enforces secure cluster connections with strong cipher suites\n- **Output Filtering**: Removes sensitive data from command output (file paths, emails, IPs, secrets)\n- **Rate Limiting**: Prevents abuse with configurable operation limits (100 req/sec default)\n- **Configuration Security**: Handles kubeconfig and environment variables securely\n\n### Enable Audit Logging\n\nAudit logging is **disabled by default**. Enable it to capture all operations:\n\n```bash\nexport KUBE_DEBUGGER_AUDIT=true\n./kube-debugger analyze my-app\n```\n\nAudit logs are stored in:\n```\n~/.kube-debugger/audit/kube-debugger-audit.log\n```\n\n### Audit Log Example\n\nEach log entry is structured JSON with complete operation details:\n\n```json\n{\n \"timestamp\": \"2026-04-22T14:21:28Z\",\n \"event_type\": \"command_execution\",\n \"username\": \"alice\",\n \"command\": \"analyze\",\n \"arguments\": [\"my-app\"],\n \"app_name\": \"my-app\",\n \"namespace\": \"production\",\n \"status\": \"success\"\n}\n```\n\n### View Audit Logs\n\n```bash\n# View last 10 audit entries\ntail -10 ~/.kube-debugger/audit/kube-debugger-audit.log\n\n# Search for failures\ngrep \"failure\" ~/.kube-debugger/audit/kube-debugger-audit.log\n\n# Monitor in real-time\ntail -f ~/.kube-debugger/audit/kube-debugger-audit.log\n```\n\n### Input Validation Examples\n\nKubeAid validates all inputs to prevent injection attacks:\n\n```bash\n# Invalid app name - REJECTED\n./kube-debugger analyze \"app;rm -rf\"\n# Error: app name contains invalid characters; must match DNS subdomain rules\n\n# Invalid namespace - REJECTED\n./kube-debugger analyze my-app -n \"invalid_ns\"\n# Error: namespace contains invalid characters\n\n# Invalid threshold - REJECTED\n./kube-debugger analyze my-app --threshold 150\n# Error: threshold must be between 0 and 100\n\n# Valid inputs - ACCEPTED\n./kube-debugger analyze my-app -n default --threshold 80\n# Success: analysis completed\n```\n\n### Secret Protection\n\nSensitive data is automatically redacted:\n\n```\nInput: connection using api_key=sk-12345abcdef and password=super-secret\nOutput: connection using api_key=[REDACTED] and password=[REDACTED]\n\nInput: Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\nOutput: Authorization: [REDACTED_JWT]\n```\n\n### Security Best Practices\n\n1. **Enable Audit Logging**: Set `KUBE_DEBUGGER_AUDIT=true` for compliance and troubleshooting\n2. **Secure Kubeconfig**: Ensure `~/.kube/config` has permissions `0600` (owner only)\n3. **Review Audit Logs**: Monitor regularly for suspicious activity\n4. **Use RBAC**: Grant kube-debugger minimal required permissions\n5. **Don't Disable TLS**: Never set `KUBECONFIG_INSECURE_SKIP_VERIFY=true` in production\n6. **Keep Updated**: Run latest version for security patches\n\n### Configuration\n\nSecurity settings can be customized via environment variables:\n\n| Variable | Description | Default |\n|---|---|---|\n| `KUBE_DEBUGGER_AUDIT` | Enable audit logging | `false` |\n| `KUBECONFIG_INSECURE_SKIP_VERIFY` | Disable cert verification (not recommended) | `false` |\n| `HOME/.kube/config` | Kubeconfig file location | `~/.kube/config` |\n\n### Audit Log Rotation\n\nAudit logs automatically rotate when they exceed 10MB:\n\n```\nkube-debugger-audit.log (current)\nkube-debugger-audit.log.1 (previous)\nkube-debugger-audit.log.2 (older)\n...\nkube-debugger-audit.log.10 (oldest)\n```\n\n### Security Documentation\n\nFor detailed security architecture, implementation, and advanced configuration, see:\n- [kube-debugger/pkg/security](kube-debugger/pkg/security) - Security implementation package\n\n## AI Configuration\n\nKubeAid supports two providers:\n- Ollama (local)\n- Groq (cloud)\n\nIf provider settings are missing or provider call fails, KubeAid falls back automatically to built-in pattern analysis.\n\nUse the repository env file:\n\n```sh\ncd kube-debugger\nsource env/kube-debugger.env\n```\n\nKey variables:\n\n| Variable | Description |\n|---|---|\n| `KUBEAID_AI_PROVIDER` | `ollama` or `groq` |\n| `KUBEAID_AI_MODEL` | Model override |\n| `KUBEAID_OLLAMA_URL` | Ollama endpoint (default `http://localhost:11434`) |\n| `KUBEAID_AI_TIMEOUT_SECONDS` | Request timeout override |\n| `GROQ_API_KEY` | Required for Groq |\n\nBootstrap helpers:\n\n```sh\ncd kube-debugger\nmake bootstrap\nmake bootstrap SKIP_KUBECONFIG_CHECK=true\n```\n\n## Why KubeAid\n- Faster first diagnosis than manually chaining `kubectl` commands\n- Suggestions are operational and copy-runnable\n- Works in local dev, CI, and multi-context environments\n\n## Contributing\nPRs and issues are welcome.\n\n## License\nApache-2.0\n"}}}} |