Kubernetes Widget

Displays the status of all pods across all namespaces in your Kubernetes cluster. Pod cards show namespace, name, image, node, phase, and restart count. Cards are color-coded by phase (green = Running/Succeeded, yellow = Pending, red = Failed). Auto-refreshes every 30 seconds.

Requirements

• A running Kubernetes cluster accessible from the server
• A valid kubeconfig file (the server reads from the default location: ~/.kube/config, or the path set by $KUBECONFIG)

Docker setup

When running Homepage in Docker, the cluster API server is typically at 127.0.0.1 or localhost in the kubeconfig, which won't resolve inside the container. The widget automatically rewrites those addresses to host.docker.internal so the container can reach your host's cluster.

Mount your kubeconfig into the container:

volumes:
  - ~/.kube/config:/root/.kube/config:ro

Or point to it with an environment variable:

environment:
  - KUBECONFIG=/root/.kube/config

Configuration

Key	Type	Default	Description
skipTlsVerify	boolean	false	Disable TLS certificate verification
hideHeader	boolean	false	Hide the widget title bar
defaultCollapsed	boolean	false	Start collapsed

Skip TLS verification

If your cluster uses a self-signed certificate, enable Skip TLS Verification in the widget settings (Settings → Widgets → Kubernetes). Only use this on trusted networks — it disables certificate validation entirely. The preferred alternative is to add your cluster's CA certificate to the kubeconfig.

Troubleshooting

No pods shown / connection error

• Confirm the kubeconfig is mounted and the path is correct
• Check that host.docker.internal resolves from inside the container (docker exec <container> ping host.docker.internal)
• Look for errors in the server logs

TLS / certificate errors

• Enable "Skip TLS Verification" in widget settings, or add your cluster CA to the kubeconfig

RBAC / permission errors

• The kubeconfig user needs at least get and list on pods across all namespaces
• Minimal ClusterRole example:

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: homepage-readonly
rules:
  - apiGroups: [""]
    resources: ["pods", "namespaces"]
    verbs: ["get", "list"]