Podminator Wiki

This is a simple, concise guide to using Podminator — the minimalist, geek-friendly terminal UI for Kubernetes. Below, you’ll find instructions on installing, configuring, and making the most of Podminator’s features.

1. Installation

1. Download the podminator binary for your platform (e.g., darwin-amd64, linux-amd64).
2. Make it executable: chmod +x podminator.
3. Ensure your local ~/.kube/config is in place for accessing your Kubernetes clusters.
4. Run ./podminator. You should see the TUI appear, ready to load contexts and namespaces.

2. Basic Navigation

• Context & Namespace:
  • Use the dropdowns at the top to select a different Kubernetes context or namespace.
  • Press c to focus the context dropdown, n for the namespace dropdown.
• Search Pods:
  • Press s to focus the search bar, type a substring of your Pod name, and watch the tree filter.
• Tree Navigation:
  • Use ↑ / ↓ to move, Enter to show details on a Pod, ← / → to collapse/expand, and / for help.

3. Logs

• Highlight a Pod in the tree, press l (lowercase “L”) to open logs.
• Use the “Tail ON/OFF” button to toggle streaming logs in real-time.
• Enter text in “Filter logs” to show only matching lines.
• Scroll with arrow keys or mouse wheel if needed.

4. Exec / Terminal

• Highlight a Pod, press e to jump into the built-in ANSI terminal. (Defaults to sh.)
• Interact as if it were a normal shell. Press Ctrl+C inside the TUI to exit or switch focus.
• Use arrow keys, Tab, and other typical shell controls as needed.

5. Metrics

• Podminator attempts to auto-discover Prometheus if available, or you can supply a -prometheus-url flag.
• Highlight a Pod, press h to see CPU/Memory usage in ASCII/Braille charts.
• The “Metrics” panel shows time-series graphs side by side if your terminal has enough space.

6. Pod “Describe” & Events

• Press Enter on a Pod in the tree to load color-coded conditions, container statuses, and recent events.
• Scroll or read thoroughly for status reasons, container restarts, and more.

7. LLM Integration

• Use ` (backtick) to open an AI summarizer powered by your local model or an Ollama server.
• This can interpret logs, Pod details, or terminal contents to give insights or suggestions.
• Specify -llm-model or -ollama-url for remote usage, or load a local model via -llm-model.

8. Refresh & Hotkeys

• Refresh: Press r to manually refresh Pods (they auto-refresh every 60s by default).
• Help Modal: Press / to see the full hotkeys list at any time.
• Ctrl+C to Quit: If in raw terminal mode, use Ctrl+C or Esc to stop or exit logs/terminals.

9. Additional Tips

• Mouse Support: You can click on dropdowns, scroll logs, or expand/collapse in the tree.
• Context Saving: Podminator remembers your last-used context/namespace for next launch.
• Prometheus Discovery: If you have an in-cluster Prom, Podminator will attempt a port-forward automatically and do a quick metrics check.

10. Troubleshooting

• Logs or Terminal not working: Check your K8s RBAC to ensure you have get / logs / exec perms.
• Metrics not showing: Ensure Prometheus is accessible or pass -prometheus-url.
• LLM queries failing: Confirm your local model or Ollama server URL is correct. Check console for error logs.
• General Errors: Run Podminator with --debug or check podminator.log if enabled for more details.