Architecture

KubeWatch is built as a set of focused microservices behind a single API gateway. Agents deployed in your infrastructure collect data and push it to the gateway over HTTPS/WSS, the gateway routes traffic to the appropriate backend service based on the request type.

System diagram

Components

API Gateway (:8000)

The single entry point for all traffic, both from agents and from the dashboard frontend. The gateway handles:

• Authentication: validates JWT tokens and API keys on every request
• Rate limiting: per-organization and per-agent request limits
• Tenant routing: extracts the org_id claim from the JWT and forwards it as a header to backend services, ensuring strict data isolation between tenants
• Reverse proxy: routes requests to the correct backend service based on path prefix

Auth Service (:8001)

Handles user login, registration, JWT issuance, and API key management. Tokens are signed with a shared JWT_SECRET and include an org_id claim that all other services use for tenant scoping.

Ingestion Service (:8002)

Receives metrics pushed by agents (container stats, pod specs, node metrics) and writes them to TimescaleDB. Agents call POST /api/v1/agents/{id}/push on a configurable interval (default: 15 seconds).

Query Service (:8003)

Serves read requests from the dashboard: container lists, pod lists, node lists, historical metrics, and the cluster summary. Queries are always scoped to the requesting organization's data.

Live-Data Service (:8009)

Manages WebSocket connections from the dashboard for real-time updates. When the ingestion service writes new data, it publishes events via Redis pub/sub; the live-data service fans those out to all connected dashboard clients subscribed to the relevant organization.

Integrations Service (:8011)

Handles connections to external databases (PostgreSQL, MySQL, Redis, Kafka) for monitoring, and outbound notification delivery to Slack, PagerDuty, SMTP, and webhooks when alerts fire.

TimescaleDB / PostgreSQL

All persistent data, metrics time-series, organizations, users, agents, alert rules, and alert history, lives in a single PostgreSQL database with the TimescaleDB extension. TimescaleDB provides automatic partitioning and compression for the metrics tables, which can grow large quickly.

Next.js Dashboard

The frontend at app.kubewatchlabs.com (or your self-hosted domain). It talks exclusively to the API gateway, it has no direct access to backend services or the database.

Deployment modes

Hosted SaaS

KubeWatch runs and maintains the gateway and all backend services. Customers deploy only the agent in their own infrastructure. Data is transmitted over TLS to the KubeWatch gateway.

• No infrastructure to manage
• Multi-tenant: your data is isolated by org_id at every layer
• Covered by KubeWatch's uptime SLA

Self-Hosted Enterprise

The complete stack runs on customer-owned infrastructure. Customers deploy both the gateway/services and the agents. No data leaves the customer's environment.

• Full data residency, nothing leaves your network
• Deploy on any Docker or Kubernetes environment
• Customer is responsible for uptime, backups, and upgrades
• Available on the Enterprise plan

Agent architecture

Agents are stateless and lightweight (< 50 MB RAM). Each agent:

1. Registers with the gateway on startup, receiving a short-lived agent token
2. Collects container/pod/node metrics from the local Docker socket or Kubernetes API
3. Pushes a JSON payload to the ingestion service every 15 seconds (configurable)
4. Maintains a persistent WebSocket connection to the live-data service for streaming log requests initiated from the dashboard

Agents require outbound HTTPS/WSS access to the gateway only, no inbound ports need to be opened on agent hosts.