home-network-k3s-impl/runbooks/monitoring-capacity.md

monitoring-capacity — The monitoring stack's own PVC is filling up

Alert: MonitoringVolumeFillingUp (warning, 15m) File: platform/monitoring/alerts.yaml, group platform-health.monitoring-self Expression: kubelet_volume_stats_available_bytes{namespace="monitoring"} / kubelet_volume_stats_capacity_bytes{namespace="monitoring"} < 0.15

What this means here

"Don't let the monitor blind itself." Prometheus or Loki is running out of disk. If it fills, you lose the ability to see every other alert in this set — which is why monitoring gets its own rule instead of sharing /runbooks/pvc-capacity (the two files partition the namespace space between them; the thresholds are deliberately identical, 15% free for 15m).

Live shape on prod:

• prometheus-...-prometheus-0 PVC 50Gi, retention: 30d, retentionSize: 45GiB
• storage-loki-0 PVC 50Gi
• both on the longhorn class, 3 replicas

retentionSize: 45GiB against a 50Gi PVC is intentional: Prometheus is supposed to plateau near the high-water mark and then stay there. So a Prometheus TSDB approaching 45 GiB is normal, not a leak. That is also why the predictive rule in pvc-capacity-alerts.yaml deliberately excludes the monitoring namespace: a TSDB filling toward its retention limit looks exactly like an unbounded leak to predict_linear until it plateaus.

So the real question is which PVC and whether it should be plateauing: read the persistentvolumeclaim label first. Loki has no size cap analogous to retentionSize, so a log volume growing past 85% is the more likely genuine problem of the two.

Running the commands in this runbook

kubectl does not work on the operator workstation. The toolchain lives only in the pinned dev container, and the host's k3s-oidc context hangs on a browser prompt once its token expires — that hang is not the cluster being down. Every command below runs as:

infra/devcontainer/dev.sh run bash -c 'kubectl --context k3s-prod get nodes'

Always pass --context k3s-prod explicitly. dev.sh merges BOTH clusters into one kubeconfig and picks a current-context per invocation, and that default has already changed once — it was k3s-dev until dev was decommissioned on 2026-09-13, and is k3s-prod now. A command that names its context means the same thing next month as it does today; one that relies on the default does not, and the failure is silent (it answers confidently about the other cluster). CLUSTER=prod infra/devcontainer/dev.sh run kubectl ... selects it explicitly, and every invocation prints a banner naming the cluster it is about to talk to — read it. Do not run two dev.sh invocations at once; they share one container and interfere.

USE FULLY-QUALIFIED RESOURCE NAMES, ALWAYS. Three CRDs on this cluster register the kind Backup: longhorn.io/v1beta2, postgresql.cnpg.io/v1 and velero.io/v1. The bare short name resolves to Longhorn's, which holds zero objects — so kubectl get backup -A prints "No resources found" on a cluster holding 6 Velero backups and 27 CNPG backups. Verified on prod 2026-09-13. Reading that as "the backups are gone" and acting on it turns a false negative into real data loss. Write backups.velero.io, backups.postgresql.cnpg.io, clusters.postgresql.cnpg.io, settings.longhorn.io, volumes.longhorn.io, nodes.longhorn.io.

Mutating kubectl (apply, patch, annotate, rollout) and flux reconcile are blocked for agents here: every durable change goes through git. main is a protected branch — a direct push is rejected. A change lands by pushing a branch, opening a PR, and merging it once the gate is green; that merge is the deploy. Where this runbook gives a mutating command it is for an operator, and it says so.

First commands

infra/devcontainer/dev.sh run bash -c \
  'kubectl --context k3s-prod -n monitoring get pvc; echo; \
   kubectl --context k3s-prod -n monitoring get prometheus -o jsonpath="{.items[0].spec.retention} {.items[0].spec.retentionSize}{\"\n\"}"'

Actual on-disk usage from inside the pods:

infra/devcontainer/dev.sh run bash -c \
  'kubectl --context k3s-prod -n monitoring exec prometheus-kube-prometheus-stack-prometheus-0 -c prometheus -- df -h /prometheus; \
   kubectl --context k3s-prod -n monitoring exec loki-0 -- df -h /var/loki'

Is Prometheus at its retentionSize (normal) or past it (a problem)?

infra/devcontainer/dev.sh run bash -c \
  'kubectl --context k3s-prod -n monitoring port-forward svc/kube-prometheus-stack-prometheus 19090:9090 & sleep 5; \
   for q in "prometheus_tsdb_storage_blocks_bytes" "prometheus_tsdb_head_series" "rate(prometheus_tsdb_compactions_failed_total[1h])"; do \
     printf "%s " "$q"; curl -s -G --data-urlencode "query=$q" localhost:19090/api/v1/query | python3 -c "import json,sys;print([x[\"value\"][1] for x in json.load(sys.stdin)[\"data\"][\"result\"]])"; done'

Series growth is the usual driver — find the biggest contributors:

infra/devcontainer/dev.sh run bash -c \
  'kubectl --context k3s-prod -n monitoring port-forward svc/kube-prometheus-stack-prometheus 19090:9090 & sleep 5; \
   curl -s "localhost:19090/api/v1/status/tsdb" | python3 -m json.tool | head -40'

Likely causes, most likely first

1. Prometheus has reached its retention high-water mark (expected)

retentionSize: 45GiB on a 50Gi PVC leaves 10% headroom, which is close to the 15% trigger. If prometheus_tsdb_storage_blocks_bytes is near 45 GiB and steady, this is the design working and the correct response is either to accept it or to raise both the PVC and retentionSize together in platform/monitoring/kube-prometheus-stack.yaml. Raising retention without raising the PVC is how you get a genuinely full disk.

2. Loki log volume growth

Loki has no retentionSize equivalent configured. A noisy workload (a crashlooping pod, a chatty reconciler) can grow it quickly. Remediation: find the noisy stream in Grafana → Explore, fix the source, and set/lower Loki retention in git.

3. Series cardinality grew after a chart or workload change

serviceMonitorSelectorNilUsesHelmValues and podMonitorSelectorNilUsesHelmValues are both false here, which means Prometheus selects every ServiceMonitor/PodMonitor in the cluster regardless of labels. That is convenient (no additionalLabels needed anywhere) and it also means a new component's monitor is picked up automatically, cardinality and all. Check /api/v1/status/tsdb for the top label pairs.

4. Compaction is failing

rate(prometheus_tsdb_compactions_failed_total[1h]) > 0 means blocks are not being merged or expired. Usually an I/O problem underneath — cross-read /runbooks/node-io.

5. The volume is on a node that is itself short of space

/runbooks/longhorn-capacity and /runbooks/node-disk.

When to escalate or stop

• Do not delete Prometheus TSDB blocks or Loki chunks by hand. Lower retention and let the component expire them; hand-deleting blocks can leave the TSDB unopenable.
• Do not raise retention or retentionSize without raising the PVC in the same change.
• If Prometheus is already full and crashlooping, you are blind: check the alerts you care about directly against the CRs (clusters.postgresql.cnpg.io, volumes.longhorn.io, kubectl get nodes) rather than waiting for alerts that cannot be evaluated.
• Escalate for PVC expansion — it needs node headroom, and this cluster has been memory- and disk-constrained before (Prometheus was already raised 2 → 3Gi of RAM after the kps 65→88 upgrade).

---

Source of truth: runbooks/monitoring-capacity.md. Index: /runbooks/ Records: platform/monitoring/pvc-capacity-alerts.yaml (why monitoring is excluded from the predictive rule); DECISIONS-LOG.md (Grafana OOM / Prometheus 2→3Gi during kps 65→88).