👋 Getting started
What is Kubernetes?
Kubernetes (often called K8s) runs your applications in containers. It keeps those containers running, moves them between machines, and starts new ones when needed.
That also means there are many moving parts. A container can run out of memory, a deployment can get stuck, or a service can lose its healthy backends.
What is kwatch?
kwatch is the alarm for your Kubernetes cluster. It watches your workloads and sends a clear message when something needs attention:
- 👀 Watch — kwatch reads Kubernetes status, events, and recent logs.
- 🧠 Explain — it connects the clues and finds the likely cause.
- 📣 Alert — it sends the reason, impact, and next step to your team.
You do not need Prometheus, Grafana, or a new dashboard to get started. kwatch is small, runs in your cluster, and keeps restart-safe incident state in Kubernetes ConfigMaps; it does not store a separate logs or metrics database.
🚨 What an alert looks like
Instead of only seeing CrashLoopBackOff, you get a message like:
🚨 OOMKilled — production / orders-api
Cause: the container used more than its 512Mi memory limit.
Next step: increase limits.memory or reduce memory usage.
Evidence: recent logs and Kubernetes events
🎯 What does kwatch watch?
Most monitors are enabled by default:
| Signal | What kwatch explains |
|---|---|
| 🟥 Pod crashes | Crash reason, logs, events, and a next step |
| ⏳ Pending pods | Why the scheduler cannot place a pod |
| 🖥️ Nodes | Readiness and disk or memory pressure |
| 🚀 Deployments | Stuck rollouts and unavailable replicas |
| 🧩 StatefulSets and DaemonSets | Unavailable or stuck workloads |
| 🧑💼 Jobs and CronJobs | Failed, suspended, or missed work |
| 📈 HPA | An autoscaler stuck at its replica limit |
| 📣 Cluster autoscaler | Evidence that scaling could not happen |
| 💾 PVCs | Storage pressure and volume failures |
| 🌐 Services and Ingress | Missing or unhealthy backends |
| 🏛️ Control plane | API server and platform health signals |
TLS certificate monitoring and heartbeat notifications are opt-in. See the configuration guide or the complete configuration reference for every available key.
🚀 Install in three steps
1. Check your tools
You need kubectl, curl, and access to a Kubernetes cluster. Confirm that
kubectl can reach it:
kubectl cluster-info
2. Run the manager
/bin/bash -c "$(curl -fsSL https://kwatch.dev/kwatch.sh)"
The manager asks where alerts should go, stores credentials safely in a Secret, installs kwatch, and waits until it is ready. No Helm is required.
3. Check the result
kubectl get pods -n kwatch
By default you should see two kwatch pods with STATUS Running: one active
leader and one standby. Both pods should show their container as READY 1/1;
only the leader is ready for monitoring. A one-replica installation is also
supported, but it has no kwatch self-failover. 🎉
🛠️ What next?
- Need the full lifecycle and troubleshooting guide? Read Installation.
- Want Slack, Discord, email, or PagerDuty? Open Channels.
- Want to change thresholds or silence known noise? Read Configuration.
- Want to understand the manager? Read kwatch.sh manager.
- Want to contribute code? Start with Contributing.
If you are unsure where to begin, install with the manager first. You can run it again later to configure, upgrade, check, or uninstall kwatch. ✨