Install on Kubernetes (Helm)

Deploy KubeWatch on Kubernetes using the official Helm chart.

The KubeWatch Helm chart deploys the full self-hosted stack onto any Kubernetes cluster, including the gateway, all backend services, PostgreSQL with TimescaleDB, Redis, and the dashboard.

This installs the complete KubeWatch platform, not just the monitoring agent. If you only want to monitor a Kubernetes cluster using hosted KubeWatch SaaS, see the [Kubernetes Agent](/agents/kubernetes) guide instead.

Prerequisites

Helm 3.10+
Kubernetes 1.26+
A default StorageClass for persistent volumes
Ingress controller (e.g., ingress-nginx, Traefik) for external access

Add the Helm repository

helm repo add kubewatch https://charts.kubewatchlabs.com
helm repo update

Install the full stack

helm install kubewatch kubewatch/kubewatch \
  --namespace kubewatch-system \
  --create-namespace \
  --set global.domain=kubewatch.example.com \
  --set global.adminEmail=admin@example.com \
  --set postgresql.password=changeme \
  --set jwt.secret=changeme-use-a-long-random-string \
  --set tls.enabled=true

Replace `changeme` values with strong, randomly generated secrets before deploying to production. Use a tool like `openssl rand -base64 32` to generate secure values.

Using a values file (recommended)

Create a kubewatch-values.yaml:

global:
  domain: "kubewatch.example.com"
  adminEmail: "admin@example.com"

tls:
  enabled: true
  # Set to "letsencrypt" to use cert-manager with Let's Encrypt
  # Set to "custom" and provide cert/key below
  issuer: "letsencrypt"

jwt:
  secret: "your-long-random-jwt-secret"

postgresql:
  password: "your-postgres-password"
  storage: "50Gi"
  storageClass: ""    # leave empty to use default StorageClass

redis:
  storage: "5Gi"

dashboard:
  replicas: 1

gateway:
  replicas: 2         # scale up for high availability

ingress:
  enabled: true
  className: "nginx"  # your ingress controller class
  annotations:
    cert-manager.io/cluster-issuer: "letsencrypt-prod"

Install using the values file:

helm install kubewatch kubewatch/kubewatch \
  --namespace kubewatch-system \
  --create-namespace \
  -f kubewatch-values.yaml

Helm values reference

Value	Default	Description
`global.domain`	`localhost`	Publicly accessible domain name
`global.adminEmail`	None	Initial admin account email
`jwt.secret`	(generated)	JWT signing secret, set explicitly in production
`postgresql.password`	(generated)	PostgreSQL password
`postgresql.storage`	`20Gi`	Persistent volume size for PostgreSQL
`redis.storage`	`2Gi`	Persistent volume size for Redis
`tls.enabled`	`false`	Enable TLS/HTTPS
`tls.issuer`	`letsencrypt`	TLS issuer: `letsencrypt` or `custom`
`ingress.enabled`	`true`	Create an Ingress resource
`ingress.className`	`nginx`	Ingress class name
`gateway.replicas`	`1`	Number of gateway replicas
`dashboard.replicas`	`1`	Number of dashboard replicas

Verify the installation

kubectl get pods -n kubewatch-system

All pods should be Running. Initial startup may take 2-3 minutes while PostgreSQL initializes and migrations run.

Check the gateway is reachable:

kubectl get ingress -n kubewatch-system

Upgrading

helm repo update
helm upgrade kubewatch kubewatch/kubewatch \
  --namespace kubewatch-system \
  -f kubewatch-values.yaml

Uninstalling

helm uninstall kubewatch -n kubewatch-system
# WARNING: this does NOT delete PersistentVolumeClaims
# Delete them manually if you want to remove all data:
kubectl delete pvc -n kubewatch-system --all