home-network-k3s-impl/runbooks/targets-down.md

targets-down — More than 10% of Prometheus scrape targets are down

Alert: PrometheusTargetsMissing (warning, 15m) File: platform/monitoring/alerts.yaml, group platform-health.monitoring-self Expression: (count(up == 0) / count(up)) > 0.10

What this means here

A tenth of everything Prometheus is supposed to scrape is unreachable. This is a blind-spot alert: its purpose is to tell you that other alerts may be silent because their data is missing, not because the thing they watch is healthy.

Live baseline on prod, measured 2026-09-13: 55 targets across 19 jobs — apiserver, cdi-prometheus-metrics, coredns, keycloak-discovery, keycloak-service, keycloak/keycloak-db, kube-prometheus-stack-alertmanager, kube-prometheus-stack-grafana, kube-prometheus-stack-operator, kube-prometheus-stack-prometheus, kube-state-metrics, kubelet, kubevirt-prometheus-metrics, nextcloud-db/nextcloud-db, node-exporter, oauth2-proxy, semaphore-db/semaphore-db, velero, velero/node-agent. So 10% is roughly 6 targets — one node's worth of exporters, or one CNPG cluster's three pods.

The far more dangerous failure this alert CANNOT see: a target that was never configured. up only counts targets Prometheus knows about. A missing ServiceMonitor produces no up == 0 series and no alert at all. This cluster has been bitten by that repeatedly, and these are the known live gaps as of 2026-09-13 — every one of them means the corresponding alerts are inert:

Missing scrape job	Alerts that cannot fire
Longhorn	LonghornVolumeDegraded, LonghornVolumeFaulted, LonghornVolumeCapacityHigh, LonghornNodeStorageHigh
cert-manager	CertificateExpiringSoon, CertificateExpiryImminent, CertificateNotReady
Flux controllers (gotk_*)	FluxReconciliationFailure, FluxResourceSuspended, ImageUpdateAutomationFailing, ImagePolicyStalled, UpdateHealthGateFailed
Hubble / Cilium (hubble_drop_total)	HubbleDeniedFlowSpike
etcd (kubeEtcd disabled for k3s, deliberately)	no etcd fsync alerting exists at all

Precedent for how costly this is: Velero shipped with three backup alerts and metrics.serviceMonitor.enabled: false, so "a nightly backup could fail — or silently stop running — for weeks with nothing to say so." That ServiceMonitor now exists. The rest of the table does not.

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 (git push origin main is the deploy). Where this runbook gives a mutating command it is for an operator, and it says so.

First commands

Which targets are down, grouped by job:

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 -G --data-urlencode "query=up == 0" localhost:19090/api/v1/query | python3 -m json.tool | grep -E "\"job\"|\"instance\"|\"namespace\"" '

The scrape-error text, which usually names the cause outright:

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/targets?state=active" | python3 -c "
import json,sys
for t in json.load(sys.stdin)[\"data\"][\"activeTargets\"]:
    if t[\"health\"]!=\"up\": print(t[\"labels\"].get(\"job\"), t[\"scrapeUrl\"], t[\"lastError\"][:120])"'

Which monitors exist at all (the gap this alert cannot see):

infra/devcontainer/dev.sh run bash -c \
  'kubectl --context k3s-prod get servicemonitors,podmonitors -A'

Likely causes, most likely first

1. A node is down or NotReady

One node takes out its node-exporter and kubelet targets together — roughly the 10% threshold on its own. Go to /runbooks/node-down; this alert is the echo.

2. A workload was rolled, scaled to zero, or crashlooped

Targets follow pods. A CNPG cluster restarting takes three targets with it. Transient; if it persists, the workload is the problem, not the monitoring.

3. A NetworkPolicy blocks the scrape

Default-deny is the baseline everywhere (R-NET-01) and a new component's monitor will be scraped the moment it exists — serviceMonitorSelectorNilUsesHelmValues: false means Prometheus selects every monitor in the cluster — so a newly added workload can produce a permanently-down target purely because nothing allows ingress from monitoring. The lastError will be a timeout. Fix is an explicit allow in the component's CiliumNetworkPolicy, in git.

4. TLS or auth on the scrape endpoint

lastError will say so (certificate or 401/403). Note a related trap from this cluster: after the Cilium upgrade, an in-cluster call to a *.home hostname is re-checked against the destination's real backend identity, so toEntities: world no longer covers it — see /runbooks/denied-flows.

5. The exporter is genuinely broken

CDI once had a broken HTTP ServiceMonitor that caused a false CDIOperatorDown, and KubeVirtControlPlaneDown once used a non-existent metric with the wrong job label. Both were fixed. An exporter that is up but publishing the wrong series is the hardest case — see /runbooks/cnpg-exporter for the canonical example (the CNPG exporter can be up=1 while its whole cnpg_pg_stat_* family is missing).

When to escalate or stop

• Treat this alert as "trust nothing else for now". Before acting on the silence of any other alert, confirm its series exists (count(<metric>)), because the table above shows five whole rule groups are currently evaluating against nothing.
• Escalate if the down targets are apiserver or kubelet — that is a control-plane problem, not a monitoring one.
• Adding a missing ServiceMonitor is a git change (a new ServiceMonitor next to the component, or a chart value). Do not "fix" a blind spot by silencing the alert.
• The Longhorn, cert-manager and Flux monitor gaps are known open work. Note them; do not try to hand-apply monitors into the cluster — every durable change goes through git.

---

Source of truth: runbooks/targets-down.md. Index: /runbooks/ Records: DECISIONS-LOG.md / commit 2d5171e (Velero had no ServiceMonitor, so three critical backup alerts could never fire); commits 6a7e9d1, b57b3e9 (the false CDI/KubeVirt alerts).