Skip to content

Kubernetes Clusters

Watchgrid can monitor and manage external Kubernetes clusters — K3s, Talos, RKE2, EKS, GKE, AKS, and others — using the lightweight cluster-agent.

How It Works

The cluster-agent runs as a Pod inside your Kubernetes cluster. It:

  1. Connects to your Watchgrid server via the WireGuard VPN
  2. Collects node health, pod counts, CPU/memory metrics
  3. Sends heartbeats with cluster status every few seconds
  4. Appears in the Watchgrid Dashboard alongside regular devices

Adding a Cluster

  1. Go to the Clusters page
  2. Click + Add Cluster
  3. Enter a cluster name (alphanumeric characters, max 63)
  4. Click Generate Manifest
  5. A Kubernetes YAML manifest is generated specifically for your cluster
  6. Click Copy to Clipboard
  7. Apply the manifest to your cluster:
kubectl apply -f watchgrid-cluster-agent.yaml

The modal shows step-by-step instructions for applying the manifest. The cluster-agent Pod will start, connect to your Watchgrid server, and begin reporting.

Cluster List

The Clusters page shows all connected clusters as expandable cards:

Card Header

  • Status indicator — green (online) or red (offline)
  • Cluster hostname and device ID
  • Kubernetes metadata — distribution, version, node count, pod count

Expanded Details

Click a cluster card to expand it and see:

Nodes Table

Column Description
Name Node hostname
Role control-plane, worker, etc.
Status Ready or NotReady
Version Kubernetes version
CPU% Current CPU utilization
Mem% Current memory utilization
Pods Number of pods on this node

Pods by Namespace

A breakdown of pods per namespace showing:

  • Running count
  • Pending count
  • Failed count
  • Total count

Additional Info

  • List of all namespaces as tag chips
  • VPN IP — the cluster-agent's WireGuard address
  • Last seen timestamp

Supported Distributions

The cluster-agent works with any Kubernetes distribution:

  • K3s — lightweight, common on edge devices
  • Talos — immutable Kubernetes OS
  • RKE2 — Rancher's hardened distribution
  • EKS — Amazon Elastic Kubernetes Service
  • GKE — Google Kubernetes Engine
  • AKS — Azure Kubernetes Service
  • kubeadm clusters
  • Any conformant Kubernetes cluster

The agent uses the standard Kubernetes API via client-go and metrics-server for resource usage.