fezzzy/pod-peek repository overview

⁠Pod-Peek

Kubernetes cluster visualization for homelabs and small clusters. Explore workloads, services, ingress, storage, and connections in an interactive graph. Compose new apps in the Designer, export Helm/YAML, and optionally apply manifests from the UI.

Prometheus is not bundled. A fresh install works without any monitoring stack. Topology and Designer work immediately; the Metrics tab stays off until you point the API at an existing Prometheus HTTP API.

⁠What you get

⁠Fresh install (no Prometheus required)

helm upgrade --install pod-peek oci://registry-1.docker.io/fezzzy/pod-peek \
  --version 0.2.17 \
  --namespace pod-peek \
  --create-namespace

Defaults:

• UI on NodePort (nginx proxies /Graph, /Namespaces, /Metrics, /Designer to the API)
• API on ClusterIP
• api.prometheus.url empty → Metrics disabled
• Designer chart/YAML download works in the browser
• Cluster deploy from Designer is off by default

⁠Open the UI

kubectl -n pod-peek get svc pod-peek-ui

Browse to http://<node-ip>:<nodePort>.

Or port-forward:

kubectl -n pod-peek port-forward svc/pod-peek-ui 8080:80
# http://127.0.0.1:8080

Helm also prints access notes after install.

⁠Optional: pod CPU / memory charts (Metrics tab)

Pod-Peek does not ship Prometheus. It queries an existing Prometheus HTTP API for pod CPU/memory history.

⁠1. Install Prometheus (separate chart)

kube-prometheus-stack⁠ is the usual choice — it scrapes kubelet/cAdvisor, which Pod-Peek needs:

helm repo add prometheus-community https://prometheus-community.github.io/helm-charts
helm repo update

helm upgrade --install kube-prom prometheus-community/kube-prometheus-stack \
  --namespace monitoring \
  --create-namespace

Wait until Prometheus is up and scraping before enabling Metrics in Pod-Peek.

⁠2. Wire Pod-Peek to Prometheus

Find your Prometheus service URL (name depends on Helm release and namespace). With release kube-prom in monitoring:

helm upgrade pod-peek oci://registry-1.docker.io/fezzzy/pod-peek \
  --version 0.2.17 \
  --namespace pod-peek \
  --reuse-values \
  --set api.prometheus.url=http://kube-prom-kube-prometheus-prometheus.monitoring.svc:9090

Or set in values:

api:
  prometheus:
    url: "http://kube-prom-kube-prometheus-prometheus.monitoring.svc:9090"

Leave url empty to disable Metrics again.

API endpoints (when configured):

• GET /Metrics/status
• GET /Metrics/pods/{namespace}
• GET /Metrics/pods/{namespace}/{pod}?range=3h

Supported lookback ranges: 30m, 3h, 12h, 7d.

⁠Homelab / K3s-style install

For NodePort, hostNetwork (when the pod network cannot reach the API server), and NFS PVC usage bars, use the chart’s values-homelab.yaml from the GitHub repo⁠ — adjust node IPs, NodePorts, and image tags for your cluster.

If you do not already run Prometheus, omit or comment out api.prometheus.url in that file. Topology and Designer still work; only Metrics needs Prometheus.

Example (local chart path):

helm upgrade --install pod-peek ./helm/pod-peek \
  -f ./helm/pod-peek/values-homelab.yaml \
  --namespace podpeek \
  --create-namespace

Common homelab toggles:

⁠Ingress

helm upgrade --install pod-peek oci://registry-1.docker.io/fezzzy/pod-peek \
  --version 0.2.17 \
  -f values-ingress.yaml \
  --namespace pod-peek \
  --create-namespace

Set ingress.enabled=true, ingress.host, and ingress.className in your values. Leave ui.apiBaseUrl empty for same-origin (UI nginx proxies API routes).

⁠Designer (compose → Helm → optional deploy)

The UI Designer tab lets you build workloads, services, ingress, PVs, and storage mounts (Topology-style — claims live on workloads, not as separate PVC nodes). Connect service ports to env vars to auto-fill in-cluster URLs like http://my-service:80.

• Download YAML — multi-document Kubernetes manifests
• Download Helm chart — zip with templates + podpeek-design.json

Cluster apply from the UI is disabled by default (API stays read-only). To enable:

designer:
  deployEnabled: true

That adds write RBAC for Deployments, Services, Ingresses, and PVCs/PVs. Prefer dry-run first; there is no auth gate yet.

⁠Install from this repository

git clone https://github.com/fezzzy/Pod-Peek.git
cd Pod-Peek

helm upgrade --install pod-peek ./helm/pod-peek \
  --namespace pod-peek \
  --create-namespace

Full value reference: helm/pod-peek/README.md

⁠Requirements

• Kubernetes 1.24+ (tested on k3s / homelab setups)
• Helm 3.8+ (OCI support for Docker Hub chart)
• Cluster read RBAC (created by the chart when rbac.create=true)
• Optional: Prometheus with kubelet/cAdvisor metrics for the Metrics tab
• Optional: NFS PVs + privileged pods for pvcDu usage bars

Images are linux/amd64.

⁠Quick reference

# Minimal install (no Prometheus)
helm upgrade --install pod-peek oci://registry-1.docker.io/fezzzy/pod-peek \
  --version 0.2.17 --namespace pod-peek --create-namespace

# Add Metrics later
helm upgrade pod-peek oci://registry-1.docker.io/fezzzy/pod-peek \
  --version 0.2.17 --namespace pod-peek --reuse-values \
  --set api.prometheus.url=http://<prometheus-service>.<namespace>.svc:9090

Links: GitHub⁠ · Chart oci://registry-1.docker.io/fezzzy/pod-peek · Images fezzzy/podpeek-api, fezzzy/podpeek-ui